环境搭建与版本管理

1. 一句话定义

环境搭建 = 让正确版本的解释器在你的终端里可用；版本管理 = 在同一台机器上并存多个 Python 版本并按项目切换。

2. 为什么重要

几乎所有初学者的第一个 bug 都不是语法错误，而是"装错了 Python / 装错了地方"。先把环境这层地基打正，后面 venv、pip、打包的学习都会顺。

3. 前置知识

kp-001；基本命令行操作（cd、ls、环境变量概念）。

4. 核心概念

• 系统 Python：macOS/Linux 自带的解释器，供系统脚本使用，不要往里面装第三方包。
• 用户安装的 Python：从 python.org、Homebrew 或版本管理器安装的独立解释器。
• 版本管理器：pyenv（经典）、uv（2024 年起的现代工具，Rust 实现，极快，集解释器/venv/pip 于一体）。
• PATH：Shell 决定"敲 python3 时执行哪个可执行文件"的查找顺序。

5. 原理与机制

python3 命令的本质是查 PATH 里的可执行文件。版本管理器通过修改 PATH（pyenv 用 shim 垫片，uv 用项目配置 .python-version）实现切换：

# 方案 A：官方安装包（最简单）
# 从 https://www.python.org/downloads/ 下载安装

# 方案 B：Homebrew（macOS）
brew install python@3.13

# 方案 C：uv（现代推荐，一行装好 uv，再由 uv 装解释器）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.13
uv python pin 3.13        # 在项目里固定版本

6. 验证清单（模型/图示）

which python3       # 应指向你安装的路径，而非 /usr/bin/python3（系统自带的）
python3 --version   # 期望 3.12+ 
python3 -m pip --version

三件事都符合预期，环境才算"立正"。

7. 直观类比

版本管理器像插座转换器：家里（机器）有多国插座标准（多个 Python 版本），出门（进项目）前按当地标准插上（pin 固定），设备就能正常工作。没有它，你会把 110V 电器插进 220V——能响，但迟早出事。

8. 实例与案例

mkdir demo && cd demo
uv python pin 3.13          # 生成 .python-version
uv init                      # 生成 pyproject.toml 骨架（见 kp-036）
uv run python                # 自动创建/复用环境并运行

没有 uv 时，后续流程见 kp-021（venv + pip）。

9. 常见误区

1. pip install 装进了系统 Python —— 后果是权限报错或污染系统依赖；正确姿势永远是虚拟环境（kp-021）。
2. python 与 python3 混淆 —— macOS 上 python 可能不存在或指向旧版本，统一用 python3 或由版本管理器接管。
3. 对着教程敲 sudo pip —— 永远不需要 sudo 装包；出现权限问题应检查装到了哪里。

10. 自测题

1. which python3 的作用是什么？为什么它比 python3 --version 更能诊断"装错版本"问题？
2. 为什么不应向系统 Python 安装第三方包？
3. uv python pin 3.13 在项目里生成了什么文件，起什么作用？

11. 与其他知识点的关系

• kp-021 虚拟环境与依赖管理：环境搭建的下一层。
• kp-036 打包与发布：环境配置的终点是"可复现的项目"。

12. 延伸阅读

• uv 官方文档：https://docs.astral.sh/uv/
• pyenv：https://github.com/pyenv/pyenv