02-环境搭建
本章代码基于 Python 3.11+ 编写
环境搭建是学习 Python 的第一步，本章使用现代工具 uv（推荐）或传统 pip。
本章讲解 Python 的安装配置和第一个程序的运行。
概念铺垫
为什么需要搭建编程环境？一个真实的对比
问题场景： 你想学习 Python，但不知道从哪里开始写代码。
不搭建环境的困惑：
- 在哪里写代码？用记事本？
- 写好的代码怎么运行？
- 代码出错了怎么调试？
- 如何安装 Python 的扩展库？
搭建环境后的清晰流程：
┌─────────────────────────────────────────────────────────┐
│ 完整的 Python 编程工作流 │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. 安装 Python 解释器 │
│ ↓ │
│ 2. 配置编辑器（VS Code） │
│ ↓ │
│ 3. 写代码 → 运行 → 查看结果 │
│ ↓ │
│ 4. 出错 → 调试 → 修正 │
│ ↓ │
│ 5. 安装扩展库 → 扩展功能 │
│ │
└─────────────────────────────────────────────────────────┘这就是编程环境的价值：提供完整的工具链，让编程过程顺畅。
编程环境解决了什么问题？
编程环境的本质是：为代码提供"生存空间"和"运行能力"。
就像鱼需要水才能游泳，代码需要环境才能运行。
编程环境的组成部分：
- Python 解释器：将代码翻译成机器能执行的指令
- 编辑器：写代码的工具（推荐 VS Code）
- 包管理器：安装和管理扩展库（推荐 uv）
- 终端/命令行：运行代码的入口
为什么推荐 uv 而非 pip？
uv 是新一代 Python 包管理器，优势：
- 🚀 速度快（比 pip 快 10-100 倍）
- 🎯 自动管理虚拟环境
- ✨ 统一工具链（pip、pip-tools、virtualenv 的功能合并）
L1 理解层：会用
环境搭建的最简流程（5分钟上手）
最简单的环境搭建只需要3步：
bash
# 步骤 1：安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 步骤 2：安装 Python
uv python install 3.11
# 步骤 3：验证安装
uv run python --version
# 输出：Python 3.11.x安装完成后，立即可以运行代码：
bash
uv run python -c "print('Hello, Python 3.11!')"
# 输出：Hello, Python 3.11!这就是环境搭建的基本流程。接下来我们详细了解各个步骤。
Windows 系统安装
安装步骤
┌─────────────────────────────────────────┐
│ Windows 安装步骤 │
├─────────────────────────────────────────┤
│ │
│ 第 1 步：下载 Python 安装包 │
│ ──────────────────────── │
│ 访问官网：https://www.python.org/ │
│ 点击 "Downloads" → 下载 Python 3.x.x │
│ │
│ 第 2 步：运行安装程序 │
│ ──────────────────────── │
│ 双击下载的 .exe 文件 │
│ │
│ 第 3 步：⚠️ 重要！勾选 PATH ⚠️ │
│ ───────────────────────────── │
│ 在安装界面底部，勾选： │
│ ☑ Add Python 3.x to PATH │
│ （添加 Python 到环境变量） │
│ │
│ ❗ 如果不勾选，后续无法在命令行使用 │
│ │
│ 第 4 步：开始安装 │
│ ──────────────────────── │
│ 点击 "Install Now" │
│ 等待安装完成（约 1-2 分钟） │
│ │
└─────────────────────────────────────────┘验证安装
cmd
# 打开命令提示符
# 按 Win + R，输入 "cmd"，按回车
# 检查 Python 版本
python --version
# 输出：Python 3.x.x
# 进入 Python 交互模式
python
# 测试代码
>>> print("Hello, World!")
Hello, World!
# 退出
>>> exit()常见问题
┌─────────────────────────────────────────┐
│ Windows 常见问题 │
├─────────────────────────────────────────┤
│ │
│ 问题：输入 python 后 Microsoft Store │
│ 弹出，而不是 Python │
│ │
│ 解决： │
│ 1. 打开 Windows "设置" │
│ 2. 进入"应用" → "应用和功能" │
│ 3. 找到"应用执行别名" │
│ 4. 关闭 python.exe 和 python3.exe │
│ │
│ ───────────────────────────────── │
│ │
│ 问题：提示"'python' 不是内部命令" │
│ │
│ 解决： │
│ 1. 重新运行 Python 安装程序 │
│ 2. 选择 "Modify"（修改） │
│ 3. 确保勾选 "Add Python to PATH" │
│ │
└─────────────────────────────────────────┘macOS 系统安装
使用 Homebrew（推荐）
bash
# 步骤 1：检查是否已安装 Homebrew
brew --version
# 步骤 2：安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 步骤 3：使用 Homebrew 安装 Python
brew install python
# 步骤 4：验证安装
python3 --version
pip3 --version使用官方安装包
bash
# 步骤 1：访问 Python 官网
https://www.python.org/downloads/mac-osx/
# 步骤 2：下载 macOS 安装程序
# 选择 "macOS 64-bit universal2 installer"
# 步骤 3：运行安装程序
# 双击下载的 .pkg 文件
# 步骤 4：验证安装
python3 --versionLinux 系统安装
Ubuntu/Debian
bash
# 更新包列表
sudo apt update
# 安装 Python 3
sudo apt install python3 python3-pip
# 验证安装
python3 --version
pip3 --versionCentOS/RHEL
bash
# 安装 EPEL 仓库
sudo yum install epel-release
# 安装 Python 3
sudo yum install python3 python3-pip
# 验证安装
python3 --version运行 Python 的两种方式
交互式模式
bash
# 进入交互模式
python # Windows
python3 # Mac/Linux
# 示例
>>> 1 + 1
2
>>> print("Hello, World!")
Hello, World!
# 退出
>>> exit()脚本文件模式
bash
# 创建文件 hello.py
print("Hello, World!")
# 运行脚本
python hello.py # Windows
python3 hello.py # Mac/Linux第一个完整程序
python
# 文件名：greeting.py
# 打印欢迎信息
print("=" * 40)
print(" 欢迎学习 Python！")
print("=" * 40)
# 获取用户输入
name = input("请问你叫什么名字？")
# 打印个性化问候
print(f"你好，{name}！很高兴见到你！")
# 获取年龄并计算出生年份
age = input("你今年多大了？")
birth_year = 2024 - int(age)
print(f"你今年{age}岁，大约出生在{birth_year}年")
# 结束
print("祝你学习愉快！")IDE 开发环境搭建
VSCode 安装与配置
概念说明
VSCode（Visual Studio Code）是微软开发的免费开源编辑器，轻量且功能强大，是 Python 初学者的首选。
安装步骤：
┌─────────────────────────────────────────────────────────────┐
│ VSCode 安装步骤 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 第 1 步：下载 VSCode │
│ ──────────────────────── │
│ 官网：https://code.visualstudio.com/ │
│ 选择对应系统版本下载 │
│ │
│ 第 2 步：安装 │
│ ──────────────────────── │
│ Windows：运行安装程序，建议勾选以下选项： │
│ ☑ 添加到 PATH │
│ ☑ 在此处打开 Code（右键菜单） │
│ │
│ Mac：拖拽到 Applications 文件夹 │
│ │
│ 第 3 步：安装 Python 扩展 │
│ ──────────────────────── │
│ 打开 VSCode → 左侧扩展图标 → 搜索 "Python" │
│ 安装 Microsoft 的 Python 扩展 │
│ │
│ 第 4 步：选择 Python 解释器 │
│ ──────────────────────── │
│ Cmd+Shift+P (Mac) / Ctrl+Shift+P (Win) │
│ 输入：Python: Select Interpreter │
│ 选择已安装的 Python 版本 │
│ │
└─────────────────────────────────────────────────────────────┘必装扩展：
| 扩展名称 | 作用 | 说明 |
|---|---|---|
| Python | 语言支持 | Microsoft 官方，必装 |
| Pylance | 智能补全 | Microsoft 官方，推荐 |
| Python Debugger | 调试器 | Microsoft 官方 |
基础配置：
json
// .vscode/settings.json（工作区配置）
{
// Python 解释器
"python.defaultInterpreterPath": "python3",
// 保存时格式化
"editor.formatOnSave": true,
// 显示空白字符
"editor.renderWhitespace": "boundary"
}运行 Python：
┌─────────────────────────────────────────────────────────────┐
│ VSCode 运行 Python 的方式 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 方式 1：右上角运行按钮 │
│ ──────────────────────── │
│ 打开 .py 文件 → 点击右上角 ▶ 按钮 │
│ │
│ 方式 2：右键菜单 │
│ ──────────────────────── │
│ 右键 → "在终端中运行 Python 文件" │
│ │
│ 方式 3：快捷键 │
│ ──────────────────────── │
│ F5：调试运行 │
│ Ctrl+F5：不调试运行 │
│ │
│ 方式 4：终端 │
│ ──────────────────────── │
│ Ctrl+` 打开终端 │
│ 输入：python 文件名.py │
│ │
└─────────────────────────────────────────────────────────────┘PyCharm 安装与配置
概念说明
PyCharm 是 JetBrains 开发的专业 Python IDE，功能强大，适合进阶学习。
版本对比：
| 版本 | 价格 | 功能 | 适用人群 |
|---|---|---|---|
| Community | 免费 | 基础功能 | 初学者、个人项目 |
| Professional | 付费 | 全功能 | 专业开发、Web 项目 |
安装步骤：
┌─────────────────────────────────────────────────────────────┐
│ PyCharm 安装步骤 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 第 1 步：下载 PyCharm │
│ ──────────────────────── │
│ 官网：https://www.jetbrains.com/pycharm/download/ │
│ 选择 Community（社区版，免费） │
│ │
│ 第 2 步：安装 │
│ ──────────────────────── │
│ Windows：运行安装程序 │
│ Mac：拖拽到 Applications 文件夹 │
│ │
│ 第 3 步：首次启动配置 │
│ ──────────────────────── │
│ • 选择 UI 主题（Darcula 深色 / Light 浅色） │
│ • 选择 Python 解释器 │
│ • 创建第一个项目 │
│ │
└─────────────────────────────────────────────────────────────┘创建项目：
┌─────────────────────────────────────────────────────────────┐
│ PyCharm 创建项目 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 第 1 步：新建项目 │
│ ──────────────────────── │
│ File → New Project │
│ │
│ 第 2 步：配置项目 │
│ ──────────────────────── │
│ • Location：项目路径 │
│ • Interpreter：选择 Python 版本 │
│ • 勾选 "Create a main.py welcome script" │
│ │
│ 第 3 步：创建 Python 文件 │
│ ──────────────────────── │
│ 右键项目 → New → Python File │
│ 输入文件名（如 hello） │
│ │
│ 第 4 步：运行代码 │
│ ──────────────────────── │
│ 右键 → Run 'hello' │
│ 或点击绿色运行按钮 │
│ │
└─────────────────────────────────────────────────────────────┘常用快捷键：
| 功能 | Mac | Windows |
|---|---|---|
| 运行 | Ctrl+Shift+R | Shift+F10 |
| 调试 | Ctrl+Shift+D | Shift+F9 |
| 格式化 | Cmd+Option+L | Ctrl+Alt+L |
| 查找 | Cmd+F | Ctrl+F |
| 全局查找 | Cmd+Shift+F | Ctrl+Shift+F |
VSCode vs PyCharm
概念说明
两个 IDE 各有特点，根据需求选择。
对比表：
┌─────────────────────────────────────────────────────────────┐
│ VSCode vs PyCharm 对比 │
├─────────────────────────────────────────────────────────────┤
│ │
│ VSCode PyCharm │
│ ───────── ───────── │
│ ✓ 免费、开源 ✓ Community 版免费 │
│ ✓ 轻量（约 100MB） ✓ 较重（约 500MB） │
│ ✓ 启动快 ✓ 启动较慢 │
│ ✓ 扩展丰富 ✓ 功能集成完整 │
│ ✓ 支持多语言 ✓ Python 专用 │
│ ✓ 配置灵活 ✓ 开箱即用 │
│ │
│ 推荐选择： │
│ ───────────────────────────────────────────── │
│ • 初学者：VSCode（轻量、免费） │
│ • 学生：VSCode 或 PyCharm Community │
│ • 专业开发：PyCharm Professional │
│ • 多语言开发：VSCode │
│ │
└─────────────────────────────────────────────────────────────┘选择建议：
| 场景 | 推荐 | 原因 |
|---|---|---|
| 初学 Python | VSCode | 轻量、上手快 |
| 学校教学 | VSCode | 免费、跨平台 |
| Web 开发 | PyCharm Pro | Django/Flask 支持 |
| 数据科学 | VSCode + Jupyter | 灵活配置 |
| 大型项目 | PyCharm | 重构、调试强大 |
提示： 工业级 VSCode 配置详见 08-工程实践篇/开发技巧/03-VSCode开发环境.md
常用命令速查
bash
# 查看 Python 版本
python --version # Windows
python3 --version # Mac/Linux
# 进入交互模式
python # Windows
python3 # Mac/Linux
# 运行脚本文件
python 文件名.py # Windows
python3 文件名.py # Mac/Linux
# 退出交互模式
exit() # 或 Ctrl+D (Mac/Linux)
# 或 Ctrl+Z 然后回车 (Windows)从简单到复杂：环境配置的渐进示例
层级1：单文件脚本
bash
# 创建并运行单个 Python 文件
uv run python hello.py层级2：创建项目结构
bash
# 初始化项目
uv init my-project
cd my-project
uv run python main.py层级3：添加依赖库
bash
# 添加第三方库
uv add requests
uv run python main.py层级4：虚拟环境管理
bash
# 创建独立环境
uv venv
source .venv/bin/activate # Linux/Mac
# 或 .venv\Scripts\activate # Windows层级5：多项目环境隔离
bash
# 不同项目使用不同 Python 版本
uv python install 3.11
uv python install 3.12
# 项目A使用 3.11
cd project-a
uv python pin 3.11
# 项目B使用 3.12
cd project-b
uv python pin 3.12综合应用：完整的 Python 项目初始化流程
这个示例展示从零创建一个完整项目：
bash
# 项目初始化完整流程（Python 3.11+）
# 1. 创建项目
uv init data-analysis-project
cd data-analysis-project
# 2. 安装 Python
uv python install 3.11
# 3. 添加依赖
uv add pandas matplotlib jupyter
# 4. 创建项目结构
mkdir -p src data notebooks tests
# 5. 创建示例代码
cat > src/main.py << 'EOF'
"""数据分析示例"""
import pandas as pd
import matplotlib.pyplot as plt
def analyze_data(file_path: str) -> pd.DataFrame:
"""读取并分析数据"""
df = pd.read_csv(file_path)
return df.describe()
if __name__ == "__main__":
result = analyze_data("data/sample.csv")
print(result)
EOF
# 6. 运行代码
uv run python src/main.py
# 7. 启动 Jupyter Notebook（交互式编程）
uv run jupyter notebook项目结构示例：
data-analysis-project/
├── pyproject.toml # 项目配置
├── src/
│ └── main.py # 主代码
├── data/
│ └── sample.csv # 数据文件
├── notebooks/
│ └── analysis.ipynb # Jupyter 笔记本
├── tests/
│ └── test_main.py # 测试代码
└── .venv/ # 虚拟环境（自动创建）L2 实践层：用好
推荐做法
| 做法 | 原因 | 示例 |
|---|---|---|
| 使用 uv 安装和管理 Python | 比官网安装更快速，自动管理版本和虚拟环境 | uv python install 3.11 |
| 每个项目创建独立虚拟环境 | 避免项目间依赖冲突，环境干净可复现 | uv venv 或 uv init my-project |
| 安装时勾选 "Add Python to PATH" | 确保命令行能直接使用 python 命令 | Windows 安装时务必勾选 |
| 用 VSCode 终端运行代码 | 新手无需额外学习终端工具，与编辑器一体化 | Ctrl+` 打开终端 |
反模式：不要这样做
python
# ❌ 错误做法：使用系统自带的 Python 直接安装全局包
pip install requests # 污染系统 Python 环境，可能导致权限问题
# ❌ 错误做法：所有项目共用一个 Python 环境
# 项目A需要 pandas==2.0，项目B需要 pandas==1.5
# 依赖冲突难以排查，环境不可复现
# ❌ 错误做法：忽略 PATH 配置
# 安装 Python 后命令行提示"'python'不是内部命令"
# 每次只能通过完整路径运行，效率极低python
# ✅ 正确做法
# 用 uv 创建独立项目环境
uv init my-project
cd my-project
uv add requests # 包安装在项目虚拟环境中，互不干扰常见安装问题与解决
| 问题 | 平台 | 原因 | 解决 |
|---|---|---|---|
'python' 不是内部或外部命令 | Windows | 未添加 Python 到 PATH | 重新安装并勾选 "Add Python to PATH" |
输入 python 弹出 Microsoft Store | Windows 10/11 | 系统启用了 Python 应用执行别名 | 设置 → 应用 → 应用执行别名 → 关闭 python.exe |
command not found: python3 | macOS/Linux | Python 未安装或路径未配置 | brew install python 或 sudo apt install python3 |
pip: command not found | macOS/Linux | 安装时未包含 pip 或路径问题 | python3 -m ensurepip --upgrade |
| 系统自带 Python 版本过旧（2.x） | macOS | macOS 自带 Python 2 已过时 | 通过 Homebrew 安装 Python 3，使用 python3 命令 |
ModuleNotFoundError 安装包后仍报错 | 跨平台 | 包装在了错误的 Python 环境 | 检查 which python 和 python -m pip list |
| VSCode 找不到 Python 解释器 | 跨平台 | 解释器路径未配置 | Cmd/Ctrl+Shift+P → Python: Select Interpreter |
externally-managed-environment 错误 | macOS (Homebrew) | Homebrew Python 禁止直接 pip install | 用 uv venv 创建虚拟环境，或用 pipx 安装全局工具 |
适用场景
| 场景 | 是否推荐 | 原因 |
|---|---|---|
| 零基础入门 | ✅ VSCode + Python 扩展 | 免费、轻量、上手快，社区教程丰富 |
| 学校机房教学 | ✅ 在线 IDE（如 Replit） | 无需本地安装，浏览器即开即用 |
| 日常学习练习 | ✅ 本地 VSCode | 离线可用，完整开发体验 |
| 公司项目开发 | ✅ PyCharm Professional | 团队协作、重构、数据库工具集成 |
| 多版本 Python 开发 | ✅ uv python pin | 不同项目可使用不同 Python 版本，互不影响 |
| 临时测试代码片段 | ✅ 交互式模式 (REPL) | 即写即执行，毫秒级反馈 |
| 生产环境部署 | ✅ Docker + uv | 环境完全一致，避免"我机器上能跑"问题 |
| 安装系统级工具（如 ruff） | ✅ pipx | 全局安装且隔离，不影响项目环境 |
本章小结
┌─────────────────────────────────────────────────────────────┐
│ 环境搭建 知识要点 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 安装要点： │
│ ✓ Windows：勾选 "Add Python to PATH" │
│ ✓ Mac：推荐使用 Homebrew │
│ ✓ Linux：使用包管理器安装 │
│ │
│ 运行方式： │
│ ✓ 交互式模式：学习、测试 │
│ ✓ 脚本文件模式：正式项目 │
│ │
│ 编辑器： │
│ ✓ VS Code（推荐新手） │
│ ✓ PyCharm（功能强大） │
│ │
│ 包管理器： │
│ ✓ uv（推荐，速度快） │
│ ✓ pip（传统工具） │
│ │
└─────────────────────────────────────────────────────────────┘