--- title: Python开发环境与工具链：VSCode、UV、Ruff date: 2024-11-06 excerpt: "从解释器、虚拟环境、依赖管理、编辑器配置到 Ruff 检查格式化，系统搭建一套现代 Python 开发工作流，并解释每一步背后的取舍。" tags: [Python, VSCode, Ruff, UV] updated: 2026-07-19 13:43:20 lang: zh-CN i18n: en: /en/python_dev_environment_and_toolchain translation: 2 --- Python 生态渐好，同一件事有很多工具可选，搭建环境时不知选谁为好，且往往要为解释器版本、虚拟环境创建、依赖管理单独下载工具，难免希望有一个All in One的工具。 这篇文章整理一套日常开发工具链： - 用 `uv` 管 Python 版本、虚拟环境和依赖。 - 用 Ruff 负责格式化、导入排序和静态检查。 - 用 `pyproject.toml` 放项目元数据和工具配置。 - 用 VS Code + Pylance 负责编辑器补全、跳转和类型提示。 `uv` 吸引人的地方首先是快，但更重要的是它把过去分散在 `pip`、`pip-tools`、`virtualenv`、`pipx`、`pyenv` 和部分项目管理工具里的能力收束到一个命令下。 ## 安装 uv 官方文档入口是 [uv docs](https://docs.astral.sh/uv/)。独立安装器不依赖本机已有 Python，更适合作为第一选择。 ```shell curl -LsSf https://astral.sh/uv/install.sh | sh ``` ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ## 管理 Python 版本 Python 项目常见的隐性问题，是作者本地用 3.12，CI 或同事机器用 3.10。语法、标准库、类型注解和依赖解析都可能因此不同。 ```shell # 查看可用版本 uv python list # 安装指定版本 uv python install 3.12 # 在当前项目固定版本 uv python pin 3.12 ``` `uv python pin` 会写入 `.python-version`。之后在项目目录里执行 `uv run`、`uv sync` 等命令时，`uv` 会优先按这个版本找解释器；找不到且允许下载时，会自动下载对应版本。 还可以在 `pyproject.toml` 里声明项目支持的 Python 范围： ```toml [project] requires-python = ">=3.12" ``` `.python-version` 和 `requires-python` 各管一层： | 文件 / 字段 | 作用 | | ------------------------- | ------------------------------------------------------ | | `.python-version` | 本地工作目录偏好的解释器版本，偏向开发体验 | | `project.requires-python` | 项目声明支持的 Python 版本范围，偏向包元数据和依赖解析 | 个人项目里可以两者都写。例如要求项目支持 `>=3.12`，本地当前固定在 `3.12` 或 `3.13`。 ## 创建项目 新项目推荐直接用 `uv init`： ```shell uv init my-app cd my-app ``` 如果当前目录已经是项目目录： ```shell uv init ``` 运行示例程序： ```shell uv run python main.py ``` 第一次执行项目命令时，`uv` 会创建 `.venv`、解析依赖，并生成 `uv.lock`。和手动激活虚拟环境相比，`uv run` 的好处是命令自带上下文：你明确在项目环境里运行，而不依赖当前 shell 是否已经激活了正确环境。 例如： ```shell uv run python --version uv run python -c "import sys; print(sys.executable)" ``` 第二条命令应该输出项目 `.venv` 里的 Python 路径。这是检查环境是否正确的最直接方法。 ## 虚拟环境：要不要手动激活 `uv` 支持两种使用方式。 第一种是不激活环境，所有命令都加 `uv run`： ```shell uv run python main.py uv run pytest uv run ruff check . ``` 这适合脚本、CI 和文档，因为命令自带上下文，不依赖 shell 状态。 第二种是激活 `.venv`，之后直接运行命令： ```shell source .venv/bin/activate python main.py deactivate ``` ```powershell .\.venv\Scripts\Activate.ps1 python main.py deactivate ``` ```nu overlay use .venv/bin/activate.nu python main.py deactivate ``` Windows 下 Nushell 的路径通常是： ```nu overlay use .venv/Scripts/activate.nu ``` 我的习惯是：日常终端里可以激活，文档和自动化脚本里尽量用 `uv run`。这样不会把「我当前 shell 的状态」变成项目构建的一部分。 ## 添加、更新和删除依赖 ```shell # 添加运行时依赖 uv add requests # 添加开发依赖 uv add --dev pytest ruff # 指定版本 uv add "ruff==0.8.0" uv add "fastapi>=0.115" # 删除依赖 uv remove requests uv remove --dev ruff # 查看依赖树 uv tree ``` 注意区分 `uv add` 和 `uv pip install`： | 命令 | 适合场景 | 是否写入项目依赖 | | --------------------------- | --------------------------------- | -------------------------------------- | | `uv add ` | 项目依赖管理 | 是，写入 `pyproject.toml` 并更新锁文件 | | `uv pip install ` | 兼容旧的 pip 工作流或临时环境操作 | 通常不改项目元数据 | | `uv run --with ` | 临时带一个包运行命令 | 不持久写入项目 | 例如临时运行一个工具： ```shell uv run --with rich python -c "from rich import print; print('[green]hello[/green]')" ``` 如果这个包是项目长期依赖，就不要用临时命令，应该 `uv add rich`。 ## 同步和锁定依赖 协作项目里，推荐提交 `uv.lock`。别人拉取项目后运行： ```shell uv sync ``` `uv sync` 会让 `.venv` 和项目声明、锁文件保持一致。根据官方 CLI 说明，项目环境不存在时会创建；默认同步会移除未声明的额外包，所以它比「只安装缺的包」更适合复现环境。 常用命令： ```shell # 只更新锁文件 uv lock # 根据锁文件同步环境 uv sync # 同步后运行命令 uv run pytest ``` 如果你需要给不使用 uv 的环境提供 `requirements.txt`，可以导出： ```shell uv export --format requirements-txt --output-file requirements.txt ``` 老的 pip-tools 风格也可以用： ```shell uv pip compile pyproject.toml -o requirements.txt uv pip sync requirements.txt ``` 选择哪一种，取决于项目边界： - 项目内部开发：优先 `uv.lock` + `uv sync`。 - 部署平台只认 `requirements.txt`：用 `uv export` 或 `uv pip compile` 生成。 - 旧项目迁移：先保留 `requirements.txt`，用 `uv pip` 接管安装速度，再慢慢迁移到 `pyproject.toml`。 ## VS Code 插件 推荐安装这些插件： - `Python` - `Pylance` - `Ruff` - `Python Debugger` - `Python postfix completion` 各自职责不同： | 插件 | 主要职责 | | ------------------------- | ------------------------------------- | | Python | 选择解释器、运行测试、调试入口 | | Pylance | 语言服务、跳转、补全、类型检查 | | Ruff | 格式化、导入排序、Lint 诊断和自动修复 | | Python Debugger | 调试 Python 程序 | | Python postfix completion | 后缀补全，提升编辑效率 | 安装插件后，先在 VS Code 命令面板里选择解释器： ```text Python: Select Interpreter ``` 选择项目里的 `.venv`。如果没有看到 `.venv`，先在项目根目录运行： ```shell uv sync ``` ## VS Code 保存时格式化和修复 在项目级 `.vscode/settings.json` 中写配置，比写全局配置更可复现。一个基础配置如下： ```json { "editor.formatOnPaste": true, "editor.formatOnSave": true, "editor.formatOnType": true, "[python]": { "editor.defaultFormatter": "charliermarsh.ruff", "editor.codeActionsOnSave": { "source.fixAll.ruff": "always", "source.organizeImports.ruff": "always" } } } ``` 这段配置的效果是：保存时用 Ruff 格式化、执行可自动修复的 lint、整理 import。 如果项目已经使用 Black，也可以用微软维护的 Black Formatter 插件。但对新项目来说，用 Ruff 同时负责格式化和 lint，配置更少，速度也更一致。 ## Pylance 配置 Pylance 负责「编辑时理解代码」。它和 Ruff 的边界要分清楚： - Ruff 更像快速代码质量工具：格式、导入、常见错误、风格规则。 - Pylance 更像语言智能：类型推断、跳转、补全、引用查找。 可以从下面这份配置开始： ```json { "python.languageServer": "Pylance", "python.analysis.cacheLSPData": true, "python.analysis.autoFormatStrings": true, "python.analysis.autoImportCompletions": true, "python.analysis.completeFunctionParens": true, "python.analysis.typeCheckingMode": "basic", "editor.inlayHints.enabled": "offUnlessPressed", "python.analysis.inlayHints.callArgumentNames": "all", "python.analysis.inlayHints.functionReturnTypes": true, "python.analysis.inlayHints.pytestParameters": true, "python.analysis.inlayHints.variableTypes": true, "python.terminal.activateEnvInCurrentTerminal": true, "python.terminal.shellIntegration.enabled": true } ``` `typeCheckingMode` 有几个常用值： | 值 | 适合场景 | | -------- | -------------------------------------------- | | `off` | 只想要补全和跳转，不想看到类型报错 | | `basic` | 日常项目推荐起点 | | `strict` | 类型约束较强的项目，或者核心库、长期维护项目 | 不建议一上来就给所有项目开 `strict`。严格类型检查很有价值，但它也会暴露很多历史代码问题。如果项目已有大量动态代码，可以先从 `basic` 开始，把新增模块写干净，再逐步提高标准。 ## Ruff：格式化和静态检查 [Ruff](https://docs.astral.sh/ruff/) 是 Astral 开发的 Python linter 和 formatter。它的 lint 规则覆盖了 Flake8、isort、pyupgrade 等工具的常用功能，formatter 则可以直接替代 Black。 安装到项目开发依赖后，常用的就四条命令： ```shell uv add --dev ruff # lint 检查 / 自动修复 uv run ruff check . uv run ruff check . --fix # 格式化 / 只检查格式不改文件（适合 CI） uv run ruff format . uv run ruff format . --check ``` Ruff 的配置可以放在 `pyproject.toml`、`ruff.toml` 或 `.ruff.toml`。项目已有 `pyproject.toml` 时，直接集中到里面通常更清爽。 ```toml [tool.ruff] line-length = 100 target-version = "py312" respect-gitignore = true indent-width = 4 [tool.ruff.format] quote-style = "double" indent-style = "space" docstring-code-format = true [tool.ruff.lint] select = [ "E", # pycodestyle error "F", # pyflakes "I", # isort "UP", # pyupgrade "B", # flake8-bugbear "SIM" # flake8-simplify ] ignore = [] ``` 几点经验： - `line-length = 100` 对现代屏幕比较舒服，团队也常用 88 或 120，关键是统一。 - `target-version` 应该和项目支持的 Python 版本一致。Ruff 会据此决定能否使用较新的语法改写。 - `select` 不要一次开太激进。先从 `E/F/I/UP/B` 开始，稳定后再扩。 - 如果你已经在 `[project]` 里写了 `requires-python`，Ruff 也能从中推断目标版本；显式写 `target-version` 时，以 Ruff 配置为准。 ## pyproject.toml 示例 `pyproject.toml` 是现代 Python 项目的中心配置文件。它来自 PEP 518 之后的生态演进，用来减少 `setup.py`、`setup.cfg`、`requirements.txt`、各种工具配置文件分散的问题。 一个常见项目可以这样写： ```toml [project] name = "vnet" version = "0.1.0" description = "Virtual network playground" readme = "README.md" requires-python = ">=3.12" dependencies = [ "pydantic>=2.10", ] [dependency-groups] dev = [ "pytest>=8.3", "pytest-cov>=6.0", "ruff", ] doc = [ "mkdocs-material>=9.5", "mkdocs-mermaid2-plugin>=1.1", ] [tool.ruff] line-length = 100 target-version = "py312" respect-gitignore = true indent-width = 4 [tool.ruff.format] quote-style = "double" indent-style = "space" docstring-code-format = true [tool.ruff.lint] select = ["E", "F", "I", "UP", "B", "SIM"] ignore = [] [tool.pytest.ini_options] addopts = "-ra" testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] log_cli = true log_cli_format = "%(asctime)s [%(levelname)s] %(message)s" log_cli_date_format = "%m.%d %H:%M:%S" ``` 几个容易踩坑的点： - `dependencies` 放运行时依赖，也就是你的包真正运行需要的库。 - `dev` 这类开发依赖不要混进运行时依赖，否则部署环境会变重。 - `pythonpath` 不建议随手写成个人机器绝对路径，例如 `/home/name/workspace/project`。这会让配置只在你的电脑上生效。更推荐采用标准包结构，或者在测试命令中明确设置。 - `indent-style = "tab"` 虽然 Ruff 支持，但 Python 社区更常见的是 space。除非团队明确要求 tab，否则不建议改。 ## 日常命令清单 下面这组命令基本覆盖个人项目从初始化到检查的流程： ```shell # 创建项目 uv init my-app cd my-app # 固定 Python 版本 uv python pin 3.12 uv sync # 添加依赖 uv add requests uv add --dev pytest ruff # 运行 uv run python main.py uv run pytest # 检查和格式化 uv run ruff check . uv run ruff check . --fix uv run ruff format . # 查看依赖 uv tree # 同步环境 uv sync ``` ## References - [uv official documentation](https://docs.astral.sh/uv/) - [uv CLI reference](https://docs.astral.sh/uv/reference/cli/) - [uv project layout](https://docs.astral.sh/uv/concepts/projects/layout/) - [Ruff documentation](https://docs.astral.sh/ruff/) - [Ruff configuration](https://docs.astral.sh/ruff/configuration/) - [Ruff editor settings](https://docs.astral.sh/ruff/editors/settings/) - [Writing your pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)