环境搭建与工具链

体系课定位

本篇是 62 篇 Python 从 0 到 1 体系课的 第 1 篇，是整个学习旅程的起点。一个趁手的开发环境决定了后续 61 篇的学习效率。磨刀不误砍柴工，这篇值得你认真走一遍。

第 1 部分：开篇导读

前置知识

零基础。你只需要一台电脑（macOS / Linux / Windows 均可）和基本的命令行操作能力。作为 Java 开发者，你已经具备这些。

学习目标

完成本篇后，你将能够：

使用 pyenv 安装并切换多个 Python 版本（3.12 / 3.13 / 3.14）
使用 venv 和 uv 创建隔离的虚拟环境
使用 pip 和 uv 安装、管理第三方依赖
配置 VS Code 和 PyCharm 两大主力 IDE
熟练使用 Python REPL（交互式解释器）进行快速验证

为什么 Java 开发者需要关注这篇？

你习惯了 IDEA 一键创建项目、Maven 自动拉依赖的体验。Python 的工具链哲学完全不同 — 轻量、灵活、组合式。没有 pom.xml 一把梭，取而代之的是 pyproject.toml + 虚拟环境 + 包管理器的三件套。理解这套工具链的设计思路，是你从 Java 思维切换到 Pythonic 思维的第一步。

第 2 部分：核心概念

阅读提示：推荐方式 vs 传统方式

本篇会同时介绍 传统工具（pyenv / venv / pip）和 现代推荐工具（uv）。为避免环境冲突（如 VIRTUAL_ENV 不匹配警告），请遵循以下原则：

标记为 「🔵 推荐」 的内容 → 请实际动手执行
标记为 「⚪ 仅供理解」 的内容 → 只看不执行，理解原理即可
如果你已经手动激活了一个虚拟环境（source .venv/bin/activate），在使用 uv run 前请先执行 deactivate，否则会出现 VIRTUAL_ENV does not match 警告

2.1 Python 解释器 vs JDK

Java 的方式

Java 开发者安装 JDK（Java Development Kit），它包含编译器 javac、运行时 java 和标准库。源码先编译为 .class 字节码，再由 JVM 执行。

Python 的方式

Python 使用 解释器（Interpreter）。最主流的实现是 CPython — 用 C 语言编写的官方参考实现。它同时扮演编译器和运行时的角色：将 .py 源码编译为字节码（.pyc），然后在 Python 虚拟机上执行。

关键差异：

维度	Java	Python
运行方式	编译 → 字节码 → JVM 执行	解释执行（内部也编译为字节码）
入口	`javac` • `java`	`python` 一步到位
版本管理	SDKMAN! / jabba	pyenv / uv
REPL	JShell（Java 9+）	内置 REPL（启动即用）

当前版本全景（2026 年 4 月）

Python 3.14.3 — 最新 Feature Release（2026-02-03 发布），引入实验性 Free-threaded 模式（no-GIL）
Python 3.13.12 — 当前 Bugfix 维护版（2026-02-03 发布），生产环境推荐
Python 3.12.x — 进入 Security-only 阶段，仍广泛使用

建议

学习和开发均使用 3.13.x（稳定且特性完整）。对 Free-threaded 模式感兴趣可额外安装 3.14。

2.2 pyenv — Python 版本管理 ⚪ 仅供理解

为什么需要版本管理？

系统自带的 Python 版本往往不可控（macOS 曾长期预装 2.7，Ubuntu 可能是 3.10）。项目 A 用 3.12，项目 B 用 3.13 — 你需要一个工具来管理多版本共存。

类比 Java 的 SDKMAN!，Python 社区用 pyenv。

选择建议

如果你只想用一个工具管理一切，直接跳到 2.3 节使用 uv。pyenv 仍被广泛使用，但 uv 已能完全替代其版本管理功能。本节内容仅供理解原理，无需实际安装 pyenv。

pyenv 的工作原理

pyenv 通过修改 PATH 环境变量中的 shims 目录 来拦截 python 命令。当你执行 python 时，实际调用的是 pyenv 的 shim 脚本，它根据以下优先级决定使用哪个版本：

PYENV_VERSION 环境变量（最高优先级）
当前目录的 .python-version 文件（pyenv local 设置）
全局默认版本（pyenv global 设置）

Mermaid

正在渲染 Mermaid 图表…

安装 pyenv（当前版本 v2.6.26）

macOS（Homebrew）：

如果没有安装 Homebrew 的可以参考官方文档。

Bash

brew update
brew install pyenv

Linux（自动安装脚本）：

Bash

curl https://pyenv.run | bash

配置 Shell（以 zsh 为例，bash 类似）：

TIP

你可以通过 echo $SHELL 直接查看当前 Shell，如果输出 /bin/zsh 说明当前使用的是 **zsh。**如果输出 /bin/bash，说明当前使用的是 bash。

Bash

# 在 ~/.zshrc 末尾追加
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

重启终端后验证：（或者直接执行 source ~/.zshrc）

Bash

pyenv --version
# 输出: pyenv 2.6.26

用 pyenv 安装 Python

Bash

# 查看可用版本
pyenv install -l | grep "^  3.13"

# 安装 Python 3.13.12
pyenv install 3.13.12

# 设置全局默认版本
pyenv global 3.13.12

# 验证
python --version
# 输出: Python 3.13.12

Windows 用户

pyenv 原生不支持 Windows。请使用 pyenv-win 或直接用 uv 管理 Python 版本（推荐）。

2.3 uv — 新一代 Python 工具链（重点推荐）

uv 是 Astral 公司用 Rust 编写的 Python 包和项目管理器，2026 年已成为 Python 社区的事实标准工具。它是 pip、pip-tools、pipx、poetry、pyenv、virtualenv 的 统一替代品，速度比 pip 快 10-100 倍。

当前版本：uv 0.11.x（2026 年 3 月）。

uv 替代了哪些工具？ 一张图看清全景：

Mermaid

正在渲染 Mermaid 图表…

类比 Java

想象一个工具同时替代了 SDKMAN! + Maven + Gradle + jenv — 这就是 uv 在 Python 生态中的定位。

安装 uv

Bash

# macOS / Linux（推荐方式）
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS（Homebrew）
brew install uv

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证
uv --version

uv 管理 Python 版本（替代 pyenv）

Bash

# 安装 Python 3.13
uv python install 3.13

# 查看已安装版本
uv python list

# 固定项目 Python 版本（写入 .python-version 文件）
uv python pin 3.13

注意

uv python pin 只是写入 .python-version 文件，不会让裸 python 命令可用。uv 管理的 Python 安装在 ~/.local/share/uv/python/ 下，不像 pyenv 那样通过 shims 拦截 python 命令。执行 python 会得到 zsh: command not found: python。

正确做法：始终使用 uv run python 代替裸 python：

Bash

# ❌ 不可用（uv 不注册裸 python 命令）
python --version

# ✅ 通过 uv run 调用（自动使用 pin 的版本）
uv run python --version
# 输出: Python 3.13.x

补救：让全局 `python` 命令可用（AI 编程工具兼容）

纯 uv 体系有一个现实问题：AI 编程工具（Codex、Claude Code、Cursor 等）在执行 tool call 时会直接调用 python script.py，而不是 uv run python script.py。如果全局没有 python 命令，这些工具会报错。

推荐方案：创建符号链接，将 uv 管理的 Python 暴露为全局 python 命令：

Bash

# 查看 uv 安装的 Python 实际路径
uv python find 3.13
# 输出示例: /Users/refinex/.local/share/uv/python/cpython-3.13-macos-aarch64-none/bin/python3.13

# 确保 ~/.local/bin 存在且在 PATH 中
mkdir -p ~/.local/bin

# 创建 python 和 python3 符号链接
ln -sf $(uv python find 3.13) ~/.local/bin/python
ln -sf $(uv python find 3.13) ~/.local/bin/python3

# 确保 ~/.local/bin 在 PATH 中（在 ~/.zshrc 追加，如果还没有的话）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
which python
# 输出: /Users/refinex/.local/bin/python
python --version
# 输出: Python 3.13.x

备选方案

如果你不想手动管理符号链接，也可以通过 Homebrew 安装一个全局 Python：brew install python@3.13。但这样会有两套 Python（Homebrew 的 + uv 的），项目开发中仍建议用 uv run。符号链接方案更轻量，且指向的就是 uv 管理的同一个 Python。

Java 对比：Maven/Gradle vs pip/uv

维度	Java（Maven/Gradle）	Python（pip/uv）
配置文件	`pom.xml` / `build.gradle`	`pyproject.toml` / `requirements.txt`
依赖仓库	Maven Central	PyPI（Python Package Index）
安装命令	`mvn install`	`pip install` / `uv add`
锁文件	（无原生支持）	`uv.lock`（uv 自动生成）
隔离机制	项目级 classpath	虚拟环境（venv）
构建工具	Maven / Gradle 一体化	pip/uv + build + twine（或 uv 一体化）

2.4 虚拟环境 — venv 与 uv

实操建议

本节介绍两种创建虚拟环境的方式。方式一（venv）为仅供理解，帮你理解虚拟环境的底层机制。方式二（uv）为推荐方式，请实际执行。不要同时执行两种方式，以免环境冲突。

为什么需要虚拟环境？

Python 的包默认安装到全局 site-packages 目录。不同项目依赖不同版本的同一个库时会冲突。虚拟环境为每个项目创建隔离的 Python 环境 — 类似 Java 中每个项目有独立的 classpath，但更彻底：连 Python 解释器的符号链接都是隔离的。

Mermaid

正在渲染 Mermaid 图表…

方式一：venv（标准库内置）⚪ 仅供理解

Bash

# 创建虚拟环境（在项目目录下）
python -m venv .venv

# 激活虚拟环境
# macOS / Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 验证：激活后提示符会显示 (.venv)
(.venv) $ python --version
(.venv) $ which python   # 指向 .venv/bin/python

# 退出虚拟环境
deactivate

方式二：uv 🔵 推荐

执行位置说明

uv venv 是在 已有项目目录内 执行的，不是随便在任何目录执行。实际上，如果你使用 uv init 创建项目（如实战 1 所示），uv 会在你第一次 uv add 或 uv run 时自动创建 .venv，无需手动执行 uv venv。本节仅展示 “单独创建虚拟环境” 这一能力，日常开发中直接用 uv init + uv run 即可。

Bash

# 在项目目录内执行（不是随便在任何目录）
mkdir py-0101-env-setup
cd py-0101-env-setup

# 创建虚拟环境
uv venv

# 或指定 Python 版本
uv venv --python 3.13

# 激活方式与 venv 相同（但用了 uv run 就不需要激活）
source .venv/bin/activate

uv 创建虚拟环境的速度比 python -m venv 快一个数量级。

实际开发中无需手动执行 `uv venv`

使用 uv init 创建项目后，第一次 uv add 或 uv run 会自动创建 .venv。同样，使用 uv run python main.py 时也 无需手动 source .venv/bin/activate。

2.5 包管理 — pip 与 uv

实操建议

pip 部分为仅供理解，帮你理解 Python 传统包管理方式。uv 部分为推荐方式，请实际执行。在新项目中请始终使用 uv add 而非 pip install。

pip（传统方式）⚪ 仅供理解

Bash

# 安装包
pip install requests

# 安装指定版本
pip install requests==2.32.3

# 从 requirements.txt 安装
pip install -r requirements.txt

# 导出当前环境依赖
pip freeze > requirements.txt

# 升级包
pip install --upgrade requests

# 卸载包
pip uninstall requests

uv（现代方式）🔵 推荐

我们下面用一个 py-0101-env-setup 项目演示：

Bash

# 项目初始化（生成 pyproject.toml）
uv init py-0101-env-setup
cd py-0101-env-setup

# 添加依赖（自动创建虚拟环境 + 安装 + 更新 lockfile）
uv add requests
uv add pytest --dev

# 安装所有依赖
uv sync

# 运行脚本（无需手动激活虚拟环境）
uv run python main.py

# 移除依赖
uv remove requests

关键差异

uv add 相当于 npm install --save，它同时修改 pyproject.toml 和 uv.lock。而 pip install 只安装到当前环境，不修改任何配置文件。

上述命令执行完你会得到一个如下的项目：

Bash

refinex@192 py-0101-env-setup % ls -la
total 24
drwxr-xr-x@ 6 refinex  staff  192  4月  4 01:29 .
drwxr-xr-x@ 4 refinex  staff  128  4月  4 01:29 ..
-rw-r--r--@ 1 refinex  staff    5  4月  4 01:29 .python-version
-rw-r--r--@ 1 refinex  staff   97  4月  4 01:29 main.py
-rw-r--r--@ 1 refinex  staff  165  4月  4 01:29 pyproject.toml
-rw-r--r--@ 1 refinex  staff    0  4月  4 01:29 README.md

每个语言都适用经典的 Hello World 开始，Python 也不例外，查看 main.py 可以看到醒目的 "Hello from py-0101-env-setup!”，其实就是一个 main 方法，和 Java 的 public static void main(String[] args) 一个意思。

if __name__ == "__main__" 的含义是：当这个文件被直接运行时才执行 main()；如果被其他文件 import，则不执行。这是 Python 的入口点惯用写法，后续篇章会详细讲解。

Bash

refinex@192 py-0101-env-setup % cat main.py
def main():
    print("Hello from py-0101-env-setup!")

if __name__ == "__main__":
    main()

直接使用 uv run python（或者 uv run --active python）就可以运行它，是不是感觉比 Javac + java 的方式快得多？

Bash

refinex@192 py-0101-env-setup % uv run python main.py
Hello from py-0101-env-setup!

2.6 IDE 配置 — VS Code 与 PyCharm

VS Code 配置

下载地址：https://code.visualstudio.com/

必装扩展：（默认就内置了）

Python（Microsoft 官方）— 语法高亮、IntelliSense、调试
Pylance — 高性能类型检查与自动补全
Ruff — 极速 Linter + Formatter（替代 flake8 + black）

工作区设置（.vscode/settings.json）：

JSON

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.analysis.typeCheckingMode": "basic",
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.codeActionsOnSave": {
            "source.fixAll": "explicit",
            "source.organizeImports": "explicit"
        }
    }
}

PyCharm 配置

PyCharm 是 JetBrains 出品的 Python IDE，Java 开发者会感到亲切 — 它和 IDEA 共享相同的 UI 框架和快捷键体系。

下载地址：https://www.jetbrains.com/pycharm

关键配置：

解释器设置：Settings → Python → Interpreter → 选择虚拟环境中的 Python
代码风格：Settings → Editor → Code Style → Python → 确保遵循 PEP 8
Ruff 集成：安装 RyeCharm 插件，替代内置 Linter

Java 对比：IDEA vs PyCharm

维度	IntelliJ IDEA	PyCharm
同一厂商	JetBrains	JetBrains
免费版	Community	Community
调试	断点 + 表达式求值	完全一致的体验
项目结构	Module + SDK	Project + Interpreter
轻量替代	—	VS Code + Python 扩展

选择建议

如果你已经习惯 JetBrains 系列，PyCharm 零学习成本。如果追求轻量和扩展性，VS Code 是 2026 年 Python 社区的主流选择。

2.7 REPL — 交互式编程

REPL（Read-Eval-Print Loop，读取-求值-输出循环）是 Python 开发者的秘密武器。你可以在终端即时执行代码、测试想法、探索 API — 不需要创建文件、不需要编译。

Java 在 9+ 版本才引入 JShell，且使用率很低。Python 的 REPL 是日常开发的核心工具。

启动方式

Bash

# 在项目目录内启动 REPL（推荐）
uv run python

# 退出 REPL：输入 exit() 或按 Ctrl+D
# Python 3.13+ 直接输入 exit 即可（无需括号）

# Python 3.13+ 增强版 REPL（多行编辑、彩色输出）
# uv run python 即可享受，无需额外配置

Python 3.13 的 REPL 改进（基于 PyPy 的交互式解释器）：

多行编辑支持（方向键可跨行移动）
彩色语法高亮
彩色异常追踪信息
支持 help、exit、quit 等命令无需加括号

IPython — 增强版 REPL

Bash

# 安装
uv add ipython --dev

# 启动（必须通过 uv run，裸 ipython 不可用）
uv run ipython

IPython 提供：Tab 自动补全、? 查看文档、%timeit 性能测试、魔术命令等高级功能。

第 3 部分：代码实战

项目实战规范

本篇所有代码实战围绕一个明确的项目展开。

项目名：py-0101-env-setup
类型：新建项目（体系课第一篇）
Python 版本：3.13
请确保已安装 uv（参见 2.3 节），然后按下方步骤操作

实战 1：从零搭建 Python 项目 🔵 推荐

Bash

# ===== 完整流程：创建本篇实战项目 =====

# 第 1 步：确保 uv 已安装
uv --version
# 输出示例: uv 0.11.2

# 第 2 步：创建项目（使用体系课命名规范）
uv init py-0101-env-setup
cd py-0101-env-setup

# 第 3 步：查看生成的项目结构(没有此命令请使用 brew install tree 安装)
tree .
# 输出:
# .
# ├── .python-version    ← Python 版本固定
# ├── README.md
# ├── main.py            ← 入口文件
# └── pyproject.toml     ← 项目配置（类似 pom.xml）

# 第 4 步：查看 pyproject.toml 内容
cat pyproject.toml

生成的 pyproject.toml（文件：pyproject.toml）：

Toml

[project]
name = "py-0101-env-setup"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

Bash

# 第 5 步：运行项目
uv run python main.py
# 输出: Hello from py-0101-env-setup!

# 第 6 步：添加依赖
uv add httpx
# uv 自动创建 .venv、安装 httpx、生成 uv.lock

# 第 7 步：验证依赖安装
uv run python -c "import httpx; print(httpx.__version__)"

添加依赖后的 pyproject.toml（文件：pyproject.toml）：

Toml

[project]
name = "py-0101-env-setup"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "httpx>=0.28.0",
]

添加依赖后的完整项目结构：

Bash

tree . -a -I '.git'
# 输出:
# .
# ├── .python-version
# ├── .venv/              ← uv 自动创建的虚拟环境（已在 .gitignore 中）
# ├── README.md
# ├── main.py
# ├── pyproject.toml
# └── uv.lock             ← 依赖锁文件

实战 2：pyenv 多版本切换 ⚪ 仅供理解

不要执行本节命令

这里展示的是 pyenv 的工作流程，帮你理解版本管理原理。实际开发中请使用 uv python install 管理版本（参见 2.3 节）。如果你已在实战 1 中完成了 uv 项目创建，请跳过本节继续实战 3。

Bash

# ===== 仅供理解：pyenv 管理多个 Python 版本的流程 =====

# 安装两个版本
pyenv install 3.12.10
pyenv install 3.13.12

# 查看已安装版本
pyenv versions
# 输出:
#   system
#   3.12.10
# * 3.13.12 (set by /Users/you/.pyenv/version)

# 全局设置
pyenv global 3.13.12
python --version
# 输出: Python 3.13.12

# 为特定项目设置版本
mkdir legacy-project && cd legacy-project
pyenv local 3.12.10
python --version
# 输出: Python 3.12.10

# 查看生成的版本文件
cat .python-version
# 输出: 3.12.10

# 回到上级目录，版本自动切回
cd ..
python --version
# 输出: Python 3.13.12

实战 3：REPL 交互式探索（Java vs Python 对比）

Java（JShell）：

Java

// 启动: jshell
jshell> String name = "World";
jshell> System.out.println("Hello, " + name + "!");
Hello, World!

jshell> List<Integer> nums = List.of(1, 2, 3, 4, 5);
jshell> nums.stream().filter(n -> n > 2).toList();
$3 ==> [3, 4, 5]

Python（REPL）：

Python

# 启动: uv run python（在项目目录内执行）
>>> name = "World"
>>> print(f"Hello, {name}!")
Hello, World!

>>> nums = [1, 2, 3, 4, 5]
>>> [n for n in nums if n > 2]
[3, 4, 5]

# 探索对象的所有方法
>>> dir(str)
['__add__', '__class__', ..., 'upper', 'zfill']

# 查看帮助文档(q 退出)
>>> help(str.split)

# 快速数学运算
>>> 2 ** 100   # Python 原生支持大整数
1267650600228229401496703205376

# 查看 Python 版本
>>> import sys
>>> sys.version
'3.13.12 (main, Mar 25 2026, 02:48:22) [Clang 22.1.1 ]'

实战 4：venv + pip 传统工作流 ⚪ 仅供理解

不要执行本节命令

这里展示的是 venv + pip 的传统工作流，帮你理解 Python 包管理的历史方式。实际开发中请使用 uv（实战 1 已演示）。混合使用两套工具会导致 VIRTUAL_ENV does not match 等环境冲突警告。

Bash

# ===== 仅供理解：传统方式（仍然有效，但推荐用 uv 替代）=====

# 创建项目目录
mkdir classic-project && cd classic-project

# 创建虚拟环境
python -m venv .venv

# 激活
source .venv/bin/activate    # macOS/Linux
# .venv\Scripts\activate     # Windows

# 安装依赖
pip install requests flask

# 导出依赖清单
pip freeze > requirements.txt
cat requirements.txt
# 输出:
# blinker==1.9.0
# certifi==2025.1.31
# ...
# flask==3.1.0
# requests==2.32.3

# 在另一台机器上还原环境
# pip install -r requirements.txt

# 退出虚拟环境
deactivate

第 4 部分：深入原理

4.1 CPython 的执行模型

当你运行 uv run python hello.py（即 python hello.py）时，CPython 内部经历以下阶段：

词法分析 + 语法分析 → 生成 AST（抽象语法树）
编译 → 将 AST 编译为字节码（bytecode），存储在 __pycache__/hello.cpython-313.pyc
执行 → Python 虚拟机（PVM）逐条执行字节码

用一张图对比 Java 和 Python 的编译执行流程：

Mermaid

正在渲染 Mermaid 图表…

本质相同 — 都是 源码 → 字节码 → 虚拟机执行。区别在于 Java 把编译和运行拆成了两条命令（javac + java），而 Python 用一条命令（python）把两步合并了，编译步骤对开发者透明。

Tip

__pycache__ 目录是 Python 的字节码缓存。下次运行同一文件时，如果源码未修改，直接加载 .pyc 跳过编译步骤。这就是为什么 Python 第二次运行比第一次快。

4.2 虚拟环境的底层机制

虚拟环境并不复制整个 Python 解释器。它的核心是：

一个 pyvenv.cfg 配置文件，记录基础解释器路径
一组 符号链接（symlink）指向系统 Python 的二进制文件
一个独立的 site-packages 目录

当虚拟环境被激活时，Shell 的 PATH 变量被修改，将 .venv/bin 插入到最前面，使得 python 和 pip 命令优先指向虚拟环境内的版本。

Bash

# 验证虚拟环境的结构
cat .venv/pyvenv.cfg
# 输出:
# home = /Users/you/.pyenv/versions/3.13.12/bin
# include-system-site-packages = false
# version = 3.13.12

4.3 PEP 标准：Python 工具链的法律

PEP 405 — Python Virtual Environments（虚拟环境规范）
PEP 517 / 518 — 构建系统接口与 pyproject.toml 的引入
PEP 621 — 在 pyproject.toml 中声明项目元数据（取代 setup.py）
PEP 723 — 内联脚本元数据（让单文件脚本声明自己的依赖）

这些 PEP 共同塑造了现代 Python 项目的标准结构。pyproject.toml 之于 Python，正如 pom.xml 之于 Java。

一句话概括

上面 4 个 PEP 的核心成果就是一个文件 — pyproject.toml。它是 Python 项目的 "身份证"，记录项目名、版本、依赖和构建方式。你现在只需要记住 pyproject.toml = 现代 Python 项目的标配，后续篇章会逐步深入每个字段的含义。

4.4 uv 为什么这么快？

uv 用 Rust 编写，核心优势在于：

并行依赖解析：同时解析多个依赖的版本约束
全局缓存：所有项目共享一个依赖缓存目录，已下载的包不会重复下载
硬链接 / COW：虚拟环境中的包文件通过硬链接指向全局缓存，几乎不占额外磁盘空间
原生 HTTP 客户端：不依赖 Python 的 urllib，直接用 Rust 的网络栈

第 5 部分：最佳实践

✅ 1. 始终使用虚拟环境

Bash

# 推荐：uv 自动管理
uv init my-project && cd my-project && uv add requests

# 或者手动创建
python -m venv .venv && source .venv/bin/activate

❌ 避免：直接 pip install 到系统 Python。这会污染全局环境，导致依赖冲突。

✅ 2. 使用 uv 作为默认包管理器

Bash

# 推荐
uv add flask
uv sync
uv run python app.py

❌ 避免：在 2026 年的新项目中仍然用 pip freeze > requirements.txt 管理依赖。

✅ 3. 固定 Python 版本到项目

Bash

# 在项目根目录创建 .python-version
echo "3.13.12" > .python-version

# 或使用 uv
uv python pin 3.13

❌ 避免：依赖「我的机器上装的是 3.x」这种隐性假设。

✅ 4. 用 pyproject.toml 统一项目配置

Toml

[project]
name = "my-app"
version = "1.0.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn>=0.34.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.9.0",
]

❌ 避免：使用 setup.py + setup.cfg + requirements.txt 三件套（已过时）。

✅ 5. 将 .venv 和 pycache 加入 .gitignore

Bash

# .gitignore
.venv/
__pycache__/
*.pyc
.python-version

✅ 6. 配置 Ruff 作为 Linter 和 Formatter

Toml

# 在 pyproject.toml 中添加
[tool.ruff]
line-length = 88
target-version = "py313"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]

✅ 7. REPL 中用 `_` 获取上一个表达式的值

Python

>>> 42 * 3
126
>>> _ + 1
127

✅ 8. 使用 `uv run` 替代手动激活虚拟环境

Bash

# 推荐：不需要 source .venv/bin/activate
uv run pytest
uv run python main.py

# 等价于
source .venv/bin/activate && pytest && deactivate

第 6 部分：动手练习

练习规范

所有练习代码均在 py-0101-env-setup 项目的 exercises/ 目录下编写。请先确保你已完成实战 1，然后：

Bash

cd py-0101-env-setup
mkdir -p exercises

练习 1 ⭐ 基础：安装并验证 Python 环境

题目：在 exercises/ex01_env_check.py 中编写代码，打印 Python 版本和当前平台信息。

预期输出（格式类似）：

Text

Python 版本: 3.13.12
平台: macOS-15.3-arm64-arm-64bit

运行命令：uv run python exercises/ex01_env_check.py

练习 2 ⭐⭐ 进阶：多版本切换

题目：使用 uv 同时安装 Python 3.12 和 3.13。创建两个目录 proj-a 和 proj-b，分别绑定不同版本，验证版本切换。

练习 3 ⭐⭐ 进阶：httpx 请求实战

题目：在 exercises/ex03_httpx_demo.py 中编写代码，使用 httpx 请求 https://httpbin.org/get 并打印响应状态码和返回的 URL 字段。

运行命令：uv run python exercises/ex03_httpx_demo.py

练习 4 ⭐⭐⭐ 挑战：对比 pip 与 uv 的速度

题目：分别使用 pip 和 uv 安装 django，用 time 命令测量耗时，将结果记录在 exercises/ex04_speed_comparison.md 中。

完成练习后的项目结构：

Bash

py-0101-env-setup/
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
├── uv.lock
└── exercises/
    ├── ex01_env_check.py
    ├── ex03_httpx_demo.py
    └── ex04_speed_comparison.md

第 7 部分：常见陷阱

陷阱 1：直接用系统 Python 装包

Java 开发者思维：「Maven 的依赖装在项目目录下的 .m2，Python 应该也差不多吧？」

❌ 错误：

Bash

# 直接用系统 pip 安装（污染全局环境）
pip install flask
pip install django
# 所有项目共享同一组依赖 → 版本冲突

✅ 正确：

Bash

# 始终在虚拟环境中安装
uv init my-project && cd my-project
uv add flask
# 依赖隔离在 .venv 中

原因：Python 的 pip install 默认行为是装到当前 Python 的 site-packages。没有虚拟环境 = 全局共享 = 灾难。

陷阱 2：混淆 python 和 python3 命令

Java 开发者思维：「java 就是 java，不会有 java3 这种东西。」

❌ 错误：

Bash

# 某些系统上 python 指向 Python 2.x
python --version
# Python 2.7.18  ← 意外！

✅ 正确：

Bash

# 方案 1：明确使用 python3
python3 --version

# 方案 2：使用 pyenv/uv 后，python 总是指向你指定的版本
pyenv global 3.13.12
python --version
# Python 3.13.12 ✓

# 方案 3：使用 uv run 完全绕过这个问题
uv run python --version

陷阱 3：忘记激活虚拟环境

Java 开发者思维：「IDE 自动处理 classpath，我从来不需要 '激活' 什么。」

❌ 错误：

Bash

# 创建了虚拟环境但没激活
python -m venv .venv
pip install flask         # 装到了系统 Python！
python app.py             # ModuleNotFoundError: No module named 'flask'

✅ 正确：

Bash

# 方案 1：手动激活
source .venv/bin/activate
pip install flask
python app.py

# 方案 2：使用 uv（完全不需要激活）
uv add flask
uv run python app.py

陷阱 4：混合使用 venv 激活与 uv run 导致环境冲突

Java 开发者思维：「我先激活虚拟环境，再用 uv run 跑代码，双保险没问题吧？」

❌ 错误：

Bash

# 先在父目录激活了一个虚拟环境
source /Users/refinex/develop/python/.venv/bin/activate

# 再进入项目目录使用 uv run
cd py-0101-env-setup
uv run python main.py
# ⚠️ warning: VIRTUAL_ENV=/Users/refinex/develop/python/.venv
#    does not match the project environment path .venv
#    and will be ignored

✅ 正确：

Bash

# 方案 1：先退出已激活的环境，再用 uv run
deactivate
uv run python main.py

# 方案 2：使用 --active 明确指向已激活的环境
uv run --active python main.py

# 方案 3（推荐）：始终使用 uv run，不手动激活任何环境
uv run python main.py

原因：uv run 会自动检测项目的 .venv。如果 Shell 中已有 VIRTUAL_ENV 环境变量指向另一个虚拟环境，uv 会发出警告。用了 uv，就不要手动 source .venv/bin/activate。

陷阱 5：在 Windows 上用 Linux 的激活命令

❌ 错误：

Bash

# Windows PowerShell 中执行
source .venv/bin/activate    # source: 找不到命令

✅ 正确：

Powershell

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat

# 或者直接用 uv（跨平台统一）
uv run python main.py

第 8 部分：总结与预告

知识点回顾

知识点	工具 / 命令	核心要点
Python 安装	pyenv / uv python	推荐 3.13.x，pyenv 或 uv 管理多版本
版本管理	pyenv / uv python pin	`.python-version` 文件固定项目版本
虚拟环境	venv / uv venv	项目级隔离，避免全局污染
包管理	pip / uv	uv 是 2026 年新项目首选
IDE 配置	VS Code / PyCharm	Python 扩展 + Ruff + 解释器指向 .venv
REPL	`uv run python` / `uv run ipython`	3.13+ 增强 REPL，即时验证的利器

自检清单

完成本篇后，你应能回答以下问题：

pyenv 是如何通过 shims 机制拦截 python 命令的？
虚拟环境的 pyvenv.cfg 文件记录了什么信息？
uv add requests 和 pip install requests 有什么本质区别？
为什么不应该直接用系统 Python 安装第三方包？
Python 3.13 的 REPL 相比旧版有哪些改进？

Git 提交提示

完成本篇所有实战和练习后，请将代码提交到 Git 仓库：

Bash

cd py-0101-env-setup
git init

# 创建 .gitignore
cat > .gitignore << 'EOF'
.venv/
__pycache__/
*.pyc
EOF

git add .
git commit -m "feat(0101): 环境搭建与工具链 - uv 项目初始化 + httpx 依赖 + 练习题"

下篇预告

环境就绪，是时候写代码了。下一篇 1-02：基础语法与数据类型，我们将对比 Java 的静态类型系统，深入 Python 的动态类型、f-string、Type Hints — 你会发现，Python 用一行代码就能完成 Java 需要五行才能表达的事情。

参考答案

参考答案

参考答案

参考答案