从零搭建Python开发环境：Python安装 + VSCode + PyCharm 完整配置指南

🐍 从零搭建Python开发环境：Python安装 + VSCode + PyCharm 完整配置指南

一、前言

Python 作为当今最流行的编程语言之一，以其简洁优雅的语法和强大的生态系统，在数据分析、人工智能、Web开发、自动化运维等领域占据着举足轻重的地位。然而，对于初学者来说，搭建一个高效、稳定的 Python 开发环境往往是入门的"第一道坎"------Python 版本怎么选？解释器是什么？IDE 之间有什么区别？环境变量又该如何配置？

本文将从零开始，手把手带你在 Windows 和 macOS 双平台上搭建一套完整的 Python 开发环境，涵盖 Python 解释器安装、包管理器配置、两大主流 IDE（VSCode 和 PyCharm）的安装与调优，以及一些能极大提升开发效率的实用技巧。

阅读本文后你将掌握：

正确安装并配置 Python 解释器（含多版本管理）

理解 PATH 环境变量与 pip 包管理器的运行机制

完成 VSCode 和 PyCharm 的完整配置与插件安装

搭建一个可直接用于实际开发的 Python 工作环境

二、Python 解释器的选择与安装

2.1 CPython vs. 其他实现

当我们谈论"Python"时，绝大多数情况下指的是 CPython------用 C 语言实现的 Python 官方解释器。除了 CPython 之外，还有一些值得了解的其他实现：

实现	特点	适用场景
CPython	官方实现，兼容性最好	日常开发、生产环境
PyPy	JIT 编译加速，纯 Python 代码运行更快	CPU 密集型任务
Anaconda	集成数据科学常用库和 conda 包管理器	数据分析、机器学习
Miniconda	Anaconda 的精简版，仅含 conda 和 Python	需要 conda 管理环境但不想要冗余包

对于绝大多数开发者，直接安装官方 CPython 是最稳妥的选择。如果你从事数据科学或机器学习领域，也可以选择 Anaconda 或 Miniconda。

2.2 Python 版本选择：3.12 / 3.11 / 3.10？

截至 2026 年，Python 的最新稳定版本为 3.13 （发布时间线见下表）。不同版本的选择需要考虑生态兼容性 和新特性需求之间的平衡：

版本	发布年份	关键新特性	生态兼容性
3.10	2021	模式匹配（`match`/`case`）、联合类型 `X	Y`
3.11	2022	比 3.10 快 10-60%、异常组（`ExceptionGroup`）	绝大多数库已支持
3.12	2023	更灵活的 f-string、更快的 `asyncio`	主流库基本支持
3.13	2024-2025	改进的交互式解释器、实验性 JIT	部分新库可能需要更新

建议： 新项目直接使用 Python 3.12+ ，如果项目依赖的第三方库较老，则选择 3.11 。本文以 Python 3.12 为例进行安装演示。

2.3 Windows 平台安装详解

第一步：下载安装包

访问 Python 官方下载页面，下载对应 Windows 版本的安装包（建议选择 Windows installer (64-bit)）。

第二步：安装过程（关键！）

安装时有一个至关重要 的勾选项------"Add Python to PATH"，请务必勾选！

bash 复制代码

# 安装完成后，打开命令提示符 (cmd) 或 PowerShell，验证安装：
python --version
# 输出示例：Python 3.12.5

pip --version
# 输出示例：pip 24.2 from C:\Python312\Lib\site-packages\pip

💡 原理说明： 勾选"Add Python to PATH"的本质是将 Python 安装目录添加到系统的 PATH 环境变量中。当你输入 python 命令时，操作系统会在 PATH 中列出的所有目录中依次查找名为 python.exe 的可执行文件。如果没有勾选此选项，你将只能在 Python 安装目录下运行 python，而无法在任意路径下调用。

第三步：验证 PATH 配置

如果在安装时忘记勾选"Add to PATH"，或者安装后 python 命令仍无法识别，可以手动检查并修复：

bash 复制代码

# 查看当前 PATH 中是否包含 Python
echo %PATH%

# 在 PowerShell 中查看
$env:Path -split ';'

# 如果缺少，手动添加到 PATH：
# 方式一：在系统环境变量中添加以下两个路径
#   C:\Python312\
#   C:\Python312\Scripts\
# 方式二：重新运行安装程序，选择 Modify → 勾选 Add to PATH

第四步：Python 交互式解释器测试

验证最基本的功能是否正常：

python 复制代码

# 在终端中输入 python 进入 REPL 模式
>>> print("Hello, Python 世界！")
Hello, Python 世界！

>>> import sys
>>> sys.version
'3.12.5 (tags/v3.12.5:0ffab53, Aug  6 2025, 13:53:06) [MSC v.1938 64 bit (AMD64)]'

>>> # 编写一个简单的函数
>>> def fibonacci(n):
...     a, b = 0, 1
...     for _ in range(n):
...         print(a, end=' ')
...         a, b = b, a + b
...
>>> fibonacci(10)
0 1 1 2 3 5 8 13 21 34

2.4 macOS 平台安装详解

方案一：Homebrew 安装（推荐）

Homebrew 是 macOS 上最流行的包管理器，使用它可以极大简化安装和升级流程：

bash 复制代码

# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python
brew install python@3.12

# 验证安装
python3 --version
pip3 --version

方案二：官方安装包

从 Python 官网下载 .pkg 安装包，双击运行即可。macOS 版本会默认安装在 /Library/Frameworks/Python.framework/Versions/3.12/ 目录下。

⚠️ 注意： macOS 系统自带的 Python 2.x（或早期版本）不要删除 ，因为系统组件依赖它。新安装的 Python 3.x 会以 python3 命令调用，与系统 Python 互不干扰。

2.5 多版本管理：pyenv

如果你需要在多个 Python 版本之间切换（例如同时维护 Python 3.10 和 3.12 的项目），pyenv 是最优雅的解决方案：

bash 复制代码

# macOS 安装 pyenv
brew install pyenv

# Windows 安装 pyenv-win（PowerShell 管理员模式）
# 方式一：使用 git
git clone https://github.com/pyenv-win/pyenv-win.git %USERPROFILE%\.pyenv
# 方式二：使用 pip
pip install pyenv-win --target %USERPROFILE%\.pyenv

# 查看可安装版本
pyenv install --list

# 安装特定版本
pyenv install 3.10.15
pyenv install 3.12.5

# 设置全局版本
pyenv global 3.12.5

# 设置项目局部版本（会在目录下生成 .python-version 文件）
cd my_project
pyenv local 3.10.15

# 查看当前使用的版本
pyenv versions

pyenv 的工作原理： 它通过 shim（垫片）机制 拦截 Python 相关命令的调用。当执行 python 命令时，pyenv 会检查当前目录（及父目录）中是否存在 .python-version 文件，若存在则使用该文件指定的 Python 版本，否则使用全局版本。这种机制实现了项目级别的 Python 版本隔离，无需手动切换环境变量。

三、pip 包管理器与国内镜像配置

3.1 pip 的核心原理

pip（Package Installer for Python）是 Python 官方推荐的包管理工具，从 Python 3.4 开始内置于标准发行版中。其核心工作机制如下：

解析依赖 ：读取 requirements.txt 或命令行指定的包名和版本约束
查询索引：默认从 PyPI (Python Package Index, https://pypi.org) 查询包元数据和分发文件
下载安装 ：下载 .whl（Wheel）或 .tar.gz（sdist）分发文件并解压到 site-packages 目录
解析传递依赖：递归安装所有依赖包，确保依赖树完整

bash 复制代码

# 常用 pip 命令一览
pip install requests           # 安装包（最新版）
pip install requests==2.31.0   # 安装指定版本
pip install "requests>=2.28"   # 安装符合版本约束的最新版
pip install -r requirements.txt  # 批量安装
pip uninstall requests         # 卸载包
pip list                       # 列出已安装包
pip show requests              # 查看包详细信息
pip freeze > requirements.txt  # 导出当前环境的所有包及版本

3.2 配置国内镜像源（大幅提升下载速度）

由于 PyPI 官方服务器位于国外，国内用户下载包时经常遇到速度慢甚至连接超时的问题。配置国内镜像源可以有效解决这一问题：

bash 复制代码

# 临时使用镜像源（单次安装）
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久配置镜像源（推荐）
# 方法一：命令行设置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 方法二：直接修改配置文件
# Windows: %APPDATA%\pip\pip.ini
# macOS/Linux: ~/.pip/pip.conf 或 ~/.config/pip/pip.conf

配置文件内容如下：

ini 复制代码

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

[install]
# 安装包时不检查已下载的 wheel 缓存
no-cache-dir = false

常用国内镜像源对比：

镜像源	地址	同步频率	稳定性
清华大学	`https://pypi.tuna.tsinghua.edu.cn/simple`	实时同步	⭐⭐⭐⭐⭐
阿里云	`https://mirrors.aliyun.com/pypi/simple/`	每日同步	⭐⭐⭐⭐⭐
中科大	`https://pypi.mirrors.ustc.edu.cn/simple/`	实时同步	⭐⭐⭐⭐
华为云	`https://repo.huaweicloud.com/repository/pypi/simple/`	每日同步	⭐⭐⭐⭐
豆瓣	`https://pypi.doubanio.com/simple/`	不定期	⭐⭐⭐

3.3 虚拟环境：隔离项目依赖的基石

在 Python 开发中，虚拟环境 是一个不可或缺的概念。它的核心思想是：为每个项目创建独立的 Python 运行环境，使不同项目可以依赖不同版本的包而互不干扰。

bash 复制代码

# 创建虚拟环境（Python 3.3+ 内置 venv 模块）
python -m venv venv

# 激活虚拟环境
# Windows (cmd):
venv\Scripts\activate
# Windows (PowerShell):
venv\Scripts\Activate.ps1
# macOS/Linux:
source venv/bin/activate

# 激活后，终端提示符会显示 (venv)
# 此时安装的包都会被隔离到 venv/Lib/site-packages 目录下
(venv) $ pip install flask

# 退出虚拟环境
deactivate

虚拟环境的底层原理： 激活虚拟环境时，它会修改当前 shell 会话的 PATH 变量，将虚拟环境的 Scripts（Windows）或 bin（Unix）目录置于系统 Python 目录之前。这样，当输入 python 或 pip 时，操作系统会优先找到虚拟环境中的可执行文件。同时，Python 解释器启动时会根据可执行文件的路径自动确定 sys.prefix，从而加载对应 site-packages 下的包。

四、VSCode 配置指南

Visual Studio Code（VSCode）是微软推出的轻量级但功能强大的代码编辑器，凭借其丰富的扩展生态和出色的性能，已成为 Python 开发者的首选工具之一。

4.1 VSCode 安装与基础设置

bash 复制代码

# 访问 https://code.visualstudio.com/ 下载安装包
# 安装时建议勾选以下选项：
#   ☑ 将"Open with Code"添加到右键菜单
#   ☑ 将 Code 注册为受支持文件类型的编辑器
#   ☑ 添加到 PATH（可从终端中使用 code 命令）

4.2 必装扩展

Python 开发在 VSCode 中需要安装以下核心扩展：

扩展名称	发布者	核心功能	推荐指数
Python	Microsoft	代码补全、智能诊断、调试、测试	⭐⭐⭐⭐⭐
Pylance	Microsoft	更快的语言服务、类型检查、代码导航	⭐⭐⭐⭐⭐
Python Debugger	Microsoft	增强的调试功能	⭐⭐⭐⭐
Jupyter	Microsoft	Jupyter Notebook 支持	⭐⭐⭐⭐
GitLens	GitKraken	Git 历史、代码作者追溯	⭐⭐⭐⭐
Error Lens	Alexander	行内错误提示	⭐⭐⭐⭐
Ruff	Astral	超高速 Python 代码检查与格式化	⭐⭐⭐⭐⭐

4.3 settings.json 深度配置

VSCode 的配置中心是 settings.json 文件。以下是一份经过优化、适合 Python 开发的完整配置：

json 复制代码

{
    // Python 相关设置
    "python.defaultInterpreterPath": "python",
    "python.terminal.activateEnvironment": true,
    "python.terminal.activateEnvInCurrentTerminal": true,
    
    // Pylance 设置
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.autoImportCompletions": true,
    "python.analysis.diagnosticMode": "workspace",
    "python.analysis.inlayHints.functionReturnTypes": true,
    "python.analysis.inlayHints.variableTypes": true,
    
    // 格式化与 linting（使用 Ruff）
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit"
        },
        "editor.defaultFormatter": "charliermarsh.ruff"
    },
    "ruff.format.args": ["--line-length=88"],
    
    // 编辑器通用设置
    "editor.fontSize": 14,
    "editor.fontFamily": "'JetBrains Mono', 'Cascadia Code', Consolas, monospace",
    "editor.minimap.enabled": false,
    "editor.bracketPairColorization.enabled": true,
    "editor.suggestSelection": "first",
    "workbench.colorTheme": "One Dark Pro",
    "files.autoSave": "onFocusChange",
    "terminal.integrated.defaultProfile.windows": "PowerShell",
    "terminal.integrated.fontSize": 13
}

4.5 调试配置：launch.json

创建 .vscode/launch.json 文件来配置调试选项：

json 复制代码

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true
        },
        {
            "name": "Python: Flask 应用",
            "type": "debugpy",
            "request": "launch",
            "module": "flask",
            "env": {
                "FLASK_APP": "app.py",
                "FLASK_DEBUG": "1"
            },
            "args": [
                "run",
                "--port=5000"
            ],
            "jinja": true
        }
    ]
}

4.6 VSCode 中的 Python 测试配置

VSCode 原生支持 pytest 和 unittest。配置 .vscode/settings.json 将其集成到 IDE 中：

json 复制代码

{
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": ["--maxfail=5", "--tb=short"],
    "python.testing.cwd": "${workspaceFolder}",
}

配置完成后，你可以在侧边栏的"测试"视图中直接运行、调试和查看测试结果，绿色对勾和红色叉号让测试状态一目了然。

五、PyCharm 配置指南

PyCharm 是 JetBrains 公司出品的专业 Python IDE，提供社区版（免费）和专业版（付费）。与 VSCode 的轻量灵活不同，PyCharm 以"开箱即用"和"深度 Python 支持"著称。

5.1 版本选择

版本	价格	核心差异
PyCharm Community	免费	仅支持纯 Python 开发，无 Web 框架支持
PyCharm Professional	付费（可试用 30 天）	支持 Django/Flask/FastAPI、SQL 数据库工具、远程解释器、Profiler
PyCharm Edu	免费	面向教育场景，内置交互式学习

建议： 日常 Python 脚本开发可以使用 Community 版；Web 开发或大型项目推荐 Professional 版（学生可申请免费教育授权）。

5.2 关键配置项

打开 File → Settings（Windows）或 PyCharm → Preferences（macOS），进行以下优化：

5.2.1 解释器配置

text 复制代码

File → Settings → Project: <name> → Python Interpreter
→ 点击齿轮图标 → Add → Existing environment → 选择虚拟环境中的 python.exe

PyCharm 会自动扫描系统中的 Python 解释器，包括 conda 环境和 venv 虚拟环境。选择正确的解释器后，PyCharm 会为代码补全、类型检查、代码导航提供准确的上下文信息。

5.2.2 代码风格配置

text 复制代码

File → Settings → Editor → Code Style → Python

关键设置：
- Line separator: Unix and macOS (\n)  ------ 保证跨平台一致性
- Hard wrap at: 120 字符（PEP 8 推荐 79，但现代项目多使用 88-120）
- 勾选 "Add trailing comma" ------ 这能让多行结构在 git diff 中更清晰

5.2.3 模板配置（文件头）

text 复制代码

File → Settings → Editor → File and Code Templates → Python Script

添加以下内容作为新建 Python 文件的默认模板：

python 复制代码

#!/usr/bin/env python3
"""
@File    :   ${NAME}.py
@Time    :   ${DATE} ${TIME}
@Author  :   ${USER}
@Version :   1.0
@Desc    :   ${DESCRIPTION}
"""

5.3 PyCharm 的杀手级功能

1. 智能代码补全与检查

PyCharm 的静态代码分析引擎极为强大。它不仅提供变量和函数的补全，还能在输入参数时自动提示函数的签名、文档字符串和预期类型。与 VSCode 的 Pylance 相比，PyCharm 的静态分析通常更深入------例如，它可以检测到未使用的导入、未处理的异常、甚至潜在的 SQL 注入风险。

2. 重构工具

text 复制代码

Refactor → Rename (Shift+F6): 智能重命名变量/函数/类，自动更新所有引用
Refactor → Extract Method (Ctrl+Alt+M): 将选中代码提取为独立函数
Refactor → Extract Variable (Ctrl+Alt+V): 将表达式提取为变量
Refactor → Move (F6): 将类/函数移动到其他模块

这些重构操作不是简单的文本替换，而是基于 AST（抽象语法树）的语义级操作，能够正确处理符号遮蔽、动态导入等复杂场景。

3. 数据库工具（Professional 版）

PyCharm Professional 内置数据库工具，可以直接连接 MySQL、PostgreSQL、SQLite 等数据库，在 IDE 中执行 SQL 查询、查看表结构、编辑数据。它还支持从 SQL 直接生成 Python 代码（如 SQLAlchemy 模型类）。

4. Profiler 性能分析

Professional 版内置了 cProfile 的可视化前端，可以直接在 IDE 中启动性能分析，结果以火焰图或调用树的形式展示，帮助快速定位性能瓶颈。

六、VSCode vs. PyCharm：如何选择？

这是一个经典的"争论"。坦率地说，两者都是优秀的开发工具，不存在绝对的优劣。我从实际使用角度给出一个客观的对比：

对比维度	VSCode	PyCharm
启动速度	⚡ 快（秒级）	🐢 较慢（10-20秒）
资源占用	💻 较低（300-500MB）	🖥️ 较高（1-2GB）
Python 智能提示	好（Pylance 加持）	优秀（开箱即用）
重构能力	基础	深度（语义级重构）
调试体验	良好	优秀（条件断点、表达式求值）
扩展生态	极丰富	有限但够用
Git 集成	基础（扩展增强）	深度集成
远程开发	支持（Remote SSH/Container）	支持（远程解释器、Gateway）
学习曲线	低（需要自行配置工具链）	中（开箱即用）
Web 开发支持	通用	专业版强（模板、ORM、JavaScript）

我的建议：

如果你喜欢**"自己组装工具链"，追求 轻量和灵活**，或者在低配置机器 上开发 → 选择 VSCode
如果你想要**"开箱即用"的一体化体验、需要 深度重构和大型项目开发，或者你的机器 配置充裕** → 选择 PyCharm

最佳实践： 很多资深开发者会同时安装两者------日常使用 VSCode 进行快速编辑和调试，复杂重构和大项目分析时切换到 PyCharm。

七、Python 开发必备工具链

除了 IDE，以下工具能进一步提升你的开发体验：

7.1 代码格式化：Ruff

Ruff 是近年来崛起的 Python 代码检查与格式化工具，使用 Rust 编写，速度比传统的 flake8 + isort + black 快 10-100 倍。更关键的是，它整合了上述多个工具的功能，一个工具即可替代一整套工具链。

bash 复制代码

# 安装
pip install ruff

# 检查代码
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

# 配置 pyproject.toml

在 pyproject.toml 中添加 Ruff 配置：

toml 复制代码

[tool.ruff]
# 目标 Python 版本
target-version = "py312"
# 行长度
line-length = 88

[tool.ruff.lint]
# 启用的规则集
select = ["E", "F", "I", "W", "UP", "N", "S"]

[tool.ruff.format]
# 与 Black 兼容的格式化风格
preview = true

7.2 类型检查：mypy

Python 是动态类型语言，但通过类型注解和 mypy 静态类型检查，可以在运行前发现大量类型相关的 bug：

bash 复制代码

pip install mypy
mypy my_script.py  # 进行类型检查

# 配置 pyproject.toml

toml 复制代码

[tool.mypy]
python_version = "3.12"
strict = true
ignore_missing_imports = true
warn_unused_ignores = true

7.3 依赖管理：pip-tools

pip-tools 通过两个文件（requirements.in 和 requirements.txt）实现了依赖的"声明式管理"，解决了直接使用 pip 时版本锁定困难的问题：

bash 复制代码

pip install pip-tools

在 requirements.in 中声明顶层依赖：

复制代码

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

然后编译生成锁定所有传递依赖版本的 requirements.txt：

bash 复制代码

pip-compile requirements.in
# 会生成完整的 requirements.txt，包含所有传递依赖及其哈希值

# 同步当前环境与 requirements.txt
pip-sync requirements.txt

7.4 预提交钩子：pre-commit

pre-commit 在每次 git commit 之前自动运行代码检查和格式化，确保所有提交的代码都符合规范：

bash 复制代码

pip install pre-commit

在项目根目录创建 .pre-commit-config.yaml：

yaml 复制代码

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
        args: ['--maxkb=500']

bash 复制代码

# 安装 pre-commit 钩子
pre-commit install

# 手动对所有文件运行一次
pre-commit run --all-files

八、完整项目目录结构示例

综合以上工具链，一个规范的 Python 项目通常采用如下目录结构：

复制代码

my_project/
├── .vscode/                    # VSCode 配置
│   ├── settings.json
│   └── launch.json
├── .venv/                      # 虚拟环境（可被 gitignore）
├── src/                        # 源代码
│   ├── __init__.py
│   ├── main.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── user.py
│   └── utils/
│       ├── __init__.py
│       └── helpers.py
├── tests/                      # 测试代码
│   ├── __init__.py
│   ├── conftest.py
│   └── test_main.py
├── docs/                       # 文档
├── scripts/                    # 辅助脚本
├── .pre-commit-config.yaml     # pre-commit 配置
├── pyproject.toml              # 项目元数据和工具配置
├── requirements.in             # 顶层依赖声明
├── requirements.txt            # 锁定后的完整依赖
├── .gitignore                  # Git 忽略规则
└── README.md                   # 项目说明

gitignore 复制代码

# .gitignore
# 虚拟环境
.venv/
venv/

# IDE 配置（团队共享的 .vscode 配置除外）
.idea/
*.iml

# Python 缓存
__pycache__/
*.py[cod]
*.pyo
*.egg-info/

# 环境变量
.env
.env.local

# 操作系统文件
.DS_Store
Thumbs.db

九、常见问题排查

9.1 "python 不是内部或外部命令"

原因： Python 安装目录未添加到系统 PATH 环境变量。

解决方案：

bash 复制代码

# Windows: 手动添加 PATH
# 1. 按 Win + R → 输入 sysdm.cpl → 高级 → 环境变量
# 2. 在"系统变量"中找到 Path → 编辑
# 3. 添加以下两项（按实际安装路径修改）：
#    C:\Python312\
#    C:\Python312\Scripts\
# 4. 重新打开终端生效

# 或者直接使用 PowerShell 临时添加：
$env:Path += ";C:\Python312\;C:\Python312\Scripts\"

9.2 pip 安装包时出现 "Connection timed out"

原因： 默认连接 PyPI 官方源，国内访问不稳定。

解决方案：

bash 复制代码

# 配置国内镜像源（见 3.2 节）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 如果某个包安装失败，尝试指定备用源
pip install numpy -i https://mirrors.aliyun.com/pypi/simple/

9.3 "No module named 'xxx'" 但已安装

原因： 通常是因为当前激活的虚拟环境不一致------你在一个环境中安装了包，但运行代码时使用的是另一个环境。

解决方案：

bash 复制代码

# 1. 确认当前解释器路径
which python   # macOS/Linux
where python   # Windows

# 2. 确认包是否安装在该解释器下
python -c "import sys; print(sys.path)"
python -m pip list | findstr xxx  # Windows
python -m pip list | grep xxx     # macOS/Linux

# 3. 确保 IDE 中选对了解释器
# VSCode: Ctrl+Shift+P → Python: Select Interpreter
# PyCharm: File → Settings → Project → Python Interpreter

9.4 pip 版本过旧导致安装失败

bash 复制代码

# 升级 pip 自身
python -m pip install --upgrade pip

如果你使用了虚拟环境，升级 pip 后虚拟环境中的 pip 也会相应更新，不影响全局安装。

十、总结

本文从零开始，详细介绍了 Python 开发环境的完整搭建过程，涵盖了以下核心内容：

章节	核心内容
Python 解释器安装	Windows/macOS 双平台安装、版本选择策略、pyenv 多版本管理
pip 包管理器	镜像源配置、虚拟环境原理与实践
VSCode 配置	扩展安装、settings.json 调优、调试配置
PyCharm 配置	版本选择、解释器与模板配置、杀手级功能
工具链	Ruff、mypy、pip-tools、pre-commit
项目结构	规范的目录布局与 gitignore

搭建好开发环境只是第一步，但它为你后续的 Python 学习之路扫清了最基础的障碍。当你能够行云流水地在编辑器之间切换、随意创建虚拟环境、熟练配置工具链时，你已经迈出了成为 Python 高手的坚实第一步。

下一篇文章，我们将深入探讨 Python 虚拟环境的进阶管理------从 conda 到 venv 再到 Poetry，为不同场景选择最合适的依赖管理方案。

📌 系列文章目录：

✅ 从零搭建Python开发环境：Python安装 + VSCode + PyCharm配置（本文）

🔜 Conda vs. venv vs. Poetry：Python虚拟环境方案对比与最佳实践

🔜 告别编码乱码：Python开发中编码问题的终极解决方案

🔜 WSL2 + Docker + Python：打造跨平台一致开发环境

🔜 终端美化与效率工具：Oh My Zsh + iTerm2 + IPython 配置指南

如果本文对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！