Python 工程实践（一）：环境搭建——pyenv、venv 与依赖地狱

1

brew install pyenv

1

curl https://pyenv.run | bash

1
2
3

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

1

source ~/.zshrc  # 或 ~/.bashrc

1
2

$ pyenv --version
pyenv 2.3.36

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ pyenv install --list | grep "^  3\." | tail -10
  3.11.5
  3.11.6
  3.11.7
  3.12.0
  3.12.1
  3.12.2
  3.12.3
  3.12.4
  3.13.0a3
  3.13.0a4

1
2
3
4

$ pyenv install 3.11.7
Downloading Python-3.11.7.tar.xz...
Installing Python-3.11.7...
Installed Python-3.11.7 to /home/user/.pyenv/versions/3.11.7

1

brew install openssl readline sqlite3 xz zlib tcl-tk

1
2
3
4

sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 全局默认（最低优先级）
$ pyenv global 3.11.7

# 按目录设置（会创建 .python-version 文件）
$ cd ~/projects/my-api
$ pyenv local 3.11.7
$ cat .python-version
3.11.7

# 仅当前 shell 会话生效（最高优先级）
$ pyenv shell 3.12.2

1
2
3
4
5
6
7
8

$ pyenv version
3.11.7 (set by /home/user/projects/my-api/.python-version)

$ pyenv versions
  system
  3.9.18
* 3.11.7 (set by /home/user/projects/my-api/.python-version)
  3.12.2

1
2

$ cd ~/projects/my-api
$ python -m venv .venv

1
2
3
4
5

.venv/
  bin/          # python、pip、activate 等脚本
  include/      # C 头文件（用于编译扩展）
  lib/          # 已安装的包存放于此
  pyvirst.cfg   # 指向基础 Python 的路径

1
2
3
4
5
6
7
8
9

# macOS / Linux
$ source .venv/bin/activate
(.venv) $

# Windows（PowerShell）
> .venv\Scripts\Activate.ps1

# Windows（cmd）
> .venv\Scripts\activate.bat

1
2
3
4
5

(.venv) $ which python
/home/user/projects/my-api/.venv/bin/python

(.venv) $ which pip
/home/user/projects/my-api/.venv/bin/pip

1
2

(.venv) $ deactivate
$

1

echo ".venv/" >> .gitignore

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 安装包
(.venv) $ pip install requests

# 安装指定版本
(.venv) $ pip install requests==2.31.0

# 安装满足约束的版本
(.venv) $ pip install "requests>=2.28,<3.0"

# 升级包
(.venv) $ pip install --upgrade requests

# 卸载包
(.venv) $ pip uninstall requests

# 查看包信息
(.venv) $ pip show requests
Name: requests
Version: 2.31.0
Location: /home/user/projects/my-api/.venv/lib/python3.11/site-packages
Requires: certifi, charset-normalizer, idna, urllib3

1
2
3
4
5

# 从当前环境生成
(.venv) $ pip freeze > requirements.txt

# 从文件安装
(.venv) $ pip install -r requirements.txt

1
2
3
4
5

certifi==2023.11.17
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.1.0

1

(.venv) $ pip install pip-tools

1
2
3
4

# requirements.in
requests>=2.28
flask>=3.0
pydantic>=2.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

(.venv) $ pip-compile requirements.in
#
# This file is autogenerated by pip-compile with Python 3.11
# by the following command:
#
#    pip-compile requirements.in
#
blinker==1.7.0
    # via flask
certifi==2023.11.17
    # via requests
charset-normalizer==3.3.2
    # via requests
click==8.1.7
    # via flask
flask==3.0.0
    # via -r requirements.in
idna==3.6
    # via requests
itsdangerous==2.1.2
    # via flask
jinja2==3.1.2
    # via flask
markupsafe==2.1.3
    # via
    #   jinja2
    #   werkzeug
pydantic==2.5.3
    # via -r requirements.in
pydantic-core==2.14.6
    # via pydantic
requests==2.31.0
    # via -r requirements.in
urllib3==2.1.0
    # via requests
werkzeug==3.0.1
    # via flask

1

(.venv) $ pip-sync requirements.txt

1
2
3
4
5

# 升级全部包
(.venv) $ pip-compile --upgrade requirements.in

# 升级单个包
(.venv) $ pip-compile --upgrade-package requests requirements.in

1
2
3
4
5
6

# requirements-dev.in
-c requirements.txt
pytest>=7.0
pytest-cov
mypy
ruff

1
2

(.venv) $ pip-compile requirements-dev.in
(.venv) $ pip-sync requirements.txt requirements-dev.txt

1
2
3
4
5
6
7
8

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS (Homebrew)
brew install uv

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

1
2
3
4
5
6
7
8
9

# 安装 Python 版本
$ uv python install 3.11 3.12 3.13

# 为项目锁定版本
$ uv python pin 3.12
Pinned `.python-version` to `3.12`

# 列出已安装版本
$ uv python list

1
2
3
4
5
6
7

# 创建新项目（含 pyproject.toml）
$ uv init my-api
$ cd my-api

# 在已有目录中初始化
$ cd existing-project
$ uv init

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 添加依赖（自动创建 venv、解析、锁定、安装——一步完成）
$ uv add requests flask "pydantic>=2.0"

# 添加开发依赖
$ uv add --dev pytest ruff mypy

# 移除依赖
$ uv remove flask

# 同步环境至锁文件状态
$ uv sync

# 升级指定包
$ uv lock --upgrade-package requests
$ uv sync

1
2
3
4
5
6
7
8

# 在项目环境中运行（自动同步依赖）
$ uv run python main.py
$ uv run pytest
$ uv run ruff check .

# 临时运行工具（无需永久安装）
$ uvx ruff check .
$ uvx black .

1
2
3
4

# 导入已有 requirements.in
$ uv add $(cat requirements.in | grep -v "^#" | grep -v "^-")

# 或直接基于 pyproject.toml（uv 直接读取 [project.dependencies]）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# .github/workflows/deps.yml
name: Dependency Check

on:
  pull_request:
    paths:
      - "pyproject.toml"
      - "requirements*.in"
      - "uv.lock"
      - "requirements*.txt"

jobs:
  check-lock:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 方案 A：uv
      - uses: astral-sh/setup-uv@v4
      - run: uv lock --check  # 若 uv.lock 过期则失败

      # 方案 B：pip-tools
      # - run: pip install pip-tools
      # - run: pip-compile --quiet requirements.in
      # - run: git diff --exit-code requirements.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# .github/dependabot.yml（用于 pip-tools）
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5

# 对于 uv：Renovate 自 v39 起原生支持 uv.lock

1
2

# 检查锁定依赖中的已知漏洞
- run: uv pip audit  # 或: pip-audit -r requirements.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 阶段 1：构建依赖（含编译工具）
FROM python:3.12-slim AS builder

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# 阶段 2：运行时（最小化镜像）
FROM python:3.12-slim AS runtime

COPY --from=builder /install /usr/local
COPY src/ /app/src/

WORKDIR /app
USER nobody
CMD ["python", "-m", "my_api"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

FROM python:3.12-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./

# 安装依赖（锁文件不变则使用缓存层）
RUN uv sync --frozen --no-dev --no-editable

COPY src/ ./src/
USER nobody
CMD ["uv", "run", "python", "-m", "my_api"]

1
2
3
4
5
6
7
8

# 错误：任何源码改动都使依赖缓存失效
COPY . .
RUN pip install -r requirements.txt

# 正确：依赖层在锁文件不变时复用
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

1

(.venv) $ pip install python-dotenv

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# settings.py
from pathlib import Path
from dotenv import load_dotenv
import os

load_dotenv()  # 读取项目根目录的 .env 文件

DATABASE_URL = os.environ["DATABASE_URL"]
API_KEY = os.environ["API_KEY"]
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"

1
2
3
4

# .env（加入 .gitignore！）
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_KEY=sk-development-key-here
DEBUG=true

1
2
3
4

# .env.example（提交到版本库——展示所需变量但不含真实值）
DATABASE_URL=postgresql://user:pass@host:5432/dbname
API_KEY=your-api-key-here
DEBUG=false

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    api_key: str
    debug: bool = False
    max_connections: int = 10
    allowed_origins: list[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"

# 若必需变量缺失，启动时立即失败并给出清晰错误
settings = Settings()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "my-api"
version = "0.1.0"
description = "A sample API project"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"},
]
dependencies = [
    "requests>=2.28",
    "flask>=3.0",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov",
    "mypy",
    "ruff",
]

[project.scripts]
my-api = "my_api.cli:main"

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.mypy]
python_version = "3.11"
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 1. 克隆仓库
$ git clone git@github.com:team/my-api.git
$ cd my-api

# 2. pyenv 自动读取 .python-version
$ python --version
Python 3.11.7

# 3. 创建并激活虚拟环境
$ python -m venv .venv
$ source .venv/bin/activate

# 4. 安装依赖
(.venv) $ pip install -r requirements.txt
# 或使用 pip-tools：
(.venv) $ pip-sync requirements.txt requirements-dev.txt

# 5. 验证测试
(.venv) $ python -m pytest
========================= test session starts ==========================
collected 42 items
...
========================= 42 passed in 3.21s ===========================

# 6. 运行应用
(.venv) $ python -m my_api
 * Running on http://127.0.0.1:5000

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

.PHONY: setup test run

setup:
	python -m venv .venv
	.venv/bin/pip install --upgrade pip
	.venv/bin/pip-sync requirements.txt requirements-dev.txt

test:
	.venv/bin/python -m pytest

run:
	.venv/bin/python -m my_api

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

my-api/
  .python-version        # pyenv 读取（已提交）
  .venv/                  # 虚拟环境（已加入 .gitignore）
  pyproject.toml          # 项目元数据与工具配置
  requirements.in         # 直接依赖声明
  requirements.txt        # 锁定的完整依赖树
  requirements-dev.in     # 开发专用直接依赖
  requirements-dev.txt    # 锁定的开发依赖树
  .gitignore              # 包含 .venv/
  src/
    my_api/
      __init__.py
      ...
  tests/
    ...