Windows与Mac下Python安装及VS Code配置详细教程

在一台新计算机上开始编写 Python 代码，核心任务由两部分组成：第一步是安装 Python 解释器并正确建立系统的全局路径关联；第二步是配置现代代码编辑器 Visual Studio Code（简称 VS Code），使之能够准确调用该解释器并提供代码自动补全、环境隔离和交互式调试能力。本文将分别针对 Windows 和 macOS 两大主流操作系统的底层机制差异，完整演示从官方源获取安装包、配置系统 PATH 环境变量、安装 VS Code 必备扩展，到创建项目虚拟环境并运行首个脚本的全流程。

一、Windows 环境下的 Python 安装与环境变量配置

在 Windows 操作系统中安装 Python 时，最容易出现的故障是命令行无法识别 python 命令，或者系统直接弹出微软应用商店界面。这是因为 Windows 依赖系统 Path 环境变量来查找可执行文件。安装时的关键在于确保二进制主程序及脚本目录被写入环境变量。

1. 获取官方安装包

访问 Python 官方网站的下载页面（https://www.python.org/downloads/windows/）。页面会自动检测系统架构并推荐适用于 64 位操作系统的安装包，文件名称通常为 python-3.x.x-amd64.exe。请直接下载该 Windows installer 安装程序，不要下载简化的 Windows embeddable package（嵌入式包缺少 pip 包管理器）。

2. 执行安装与关键选项设置

双击运行下载完成的安装程序，安装向导界面将包含两个极易被忽略但至关重要的单选与复选框：

• 勾选底部的“Add python.exe to PATH”：这一项默认处于未勾选状态。必须手动将其勾选。该选项会自动将 Python 解释器目录（如 C:\Users\<用户名>\AppData\Local\Programs\Python\Python3xx\）和脚本目录（Scripts\）添加到当前用户的 Path 环境变量中。
• 选择“Customize installation”（自定义安装）：点击自定义安装可以清晰审查安装组件。在 Optional Features（可选功能）页面中，确认 Documentation、pip、tcl/tk and IDLE、Python test suite 以及 py launcher（启动器）均保持选中状态。
• 高级选项设置（Advanced Options）：勾选“Install Python for all users”（为所有用户安装，安装路径将简化为 C:\Program Files\Python3xx，便于团队统一管理），同时建议勾选“Precompile standard library”（预编译标准库，加速初次模块加载）。
• 解除最大路径长度限制：安装完成后，若界面出现“Disable path length limit”按钮，建议点击确认。该操作可移除 Windows 历史上默认的 260 字符路径上限，防止深度嵌套的第三方包在安装时报错。

3. Windows 终端验证

按下快捷键 Win + R，输入 powershell 或 cmd 回车，打开命令行终端，执行以下两条验证命令：

# 检查 Python 解释器版本
python --version

# 检查包管理器版本与安装路径
pip --version

示例输出结果如下：

Python 3.12.3
pip 24.0 from C:\Program Files\Python312\Lib\site-packages\pip (python 3.12)

二、macOS 环境下的 Python 安装与路径管理

macOS 系统在历史版本中曾预装过 Python 2.7（现已移除），现代 macOS 安装 Xcode Command Line Tools 后会提供一个位于 /usr/bin/python3 的精简环境。但系统环境通常不包含 pip，且受系统完整性保护（SIP）限制，不适合用于实际开发。在 Mac 上配置 Python 必须使用用户空间安装方案。

1. 两种主流安装方式

macOS 下推荐两种安装途径，读者可根据自身使用习惯二选一：

• 途径 A：官方 PKG 安装器（推荐新手）：访问 Python 官网 macOS 下载页，下载 macOS 64-bit universal2 installer（通用二进制安装包，原生支持 Apple Silicon M系列与 Intel 芯片）。双击安装包，一路按照向导点击“继续”即可完成。该安装包不仅包含完整的解释器和 pip，还自带 certificates 根证书配置脚本。
• 途径 B：通过 Homebrew 包管理器（推荐已有开发环境的用户）：在 macOS Terminal 中执行包管理命令，无需手动下载文件即可全自动维护多版本：

  # 使用 Homebrew 安装最新稳定版 Python
  brew install python

2. macOS 终端验证与证书处理

打开 macOS 的“终端”（Terminal.app），运行版本检测命令。请注意，在 macOS 环境下，必须显式使用 python3 和 pip3 指令：

# 检查 Python 3 版本
python3 --version

# 检查 pip3 对应安装位置
pip3 --version

# 查看当前 python3 的真实二进制绝对路径
which python3

示例输出：

Python 3.12.3
pip 24.0 from /Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/pip (python 3.12)
/Library/Frameworks/Python.framework/Versions/3.12/bin/python3

三、Visual Studio Code 的安装与必备插件配置

Python 解释器就绪后，需要搭配现代开发工具。VS Code 本身是一个通用的文本编辑器，通过安装官方的 Python 扩展插件，才能将其转变为具备语法分析、静态检查、智能补全和调试能力的完整 IDE。

1. 下载与安装 VS Code

访问官方站点 https://code.visualstudio.com/ 下载适用于当前系统的版本：

• Windows 用户：下载 User Installer（64-bit）。在安装过程的“选择其他任务”界面，强烈勾选“添加到 PATH”以及“将‘通过 Code 打开’操作添加到 Windows 资源管理器文件上下文菜单”。
• macOS 用户：下载 .zip 压缩包，解压后得到 Visual Studio Code.app，将其拖拽移动到系统 /Applications（应用程序）文件夹中。随后在 VS Code 内部按下快捷键 Cmd + Shift + P，输入 Shell Command: Install 'code' command in PATH 并回车，以便在系统终端中直接用 code . 打开当前目录。

2. 安装核心扩展

打开 VS Code，点击左侧活动栏的扩展图标（快捷键 Ctrl+Shift+X / Cmd+Shift+X），在搜索栏输入并安装以下扩展：

• Python（由 Microsoft 官方出品）：核心扩展。安装后会自动附带安装 Pylance（高性能语言服务器，提供类型推断与代码自动补全）和 Python Debugger（基于 debugpy 的交互式断点调试器）。
• Chinese (Simplified) Language Pack（可选）：由 Microsoft 出品的简体中文语言包，安装后重启 VS Code 即可将操作界面汉化。

四、首个项目：创建工作区、虚拟环境与调试运行

在实际开发中，不建议直接把第三方库安装到系统全局。最佳实践是为每个项目创建专属的“虚拟环境”（Virtual Environment）。VS Code 对 Python 官方的 venv 模块提供了无缝集成。

1. 创建项目目录并在 VS Code 中打开

打开系统终端，执行以下命令新建一个工程目录并由 VS Code 打开：

# 创建目录并进入
mkdir python_demo
cd python_demo

# 使用 VS Code 打开当前工作区
code .

2. 创建与配置项目专属虚拟环境

在 VS Code 顶部菜单栏点击“终端” -> “新建终端”（快捷键 Ctrl+` 或 Cmd+`）。在下方弹出的集成终端中，根据操作系统输入对应命令：

# Windows 系统 (PowerShell 或 CMD)
python -m venv .venv

# macOS 系统 (zsh 或 bash)
python3 -m venv .venv

命令执行完成后，项目左侧文件树中会出现一个名为 .venv 的文件夹。此时 VS Code 会弹出一个提示框：“已检测到创建了新的虚拟环境。是否要将其选为工作区文件夹的环境？”，直接点击“是”（Yes）。

如果未弹出提示，读者可手动指定：按下 Ctrl+Shift+P（Windows）或 Cmd+Shift+P（Mac），输入 Python: Select Interpreter，在列表中直接选择带有 ('.venv': venv) 标记的解释器项。

3. 编写与运行代码

在项目根目录下新建名为 main.py 的文件，输入以下测试代码：

import sys
import platform

def main():
    print("Python 环境配置成功！")
    print(f"操作系统版本: {platform.platform()}")
    print(f"解释器二进制路径: {sys.executable}")
    print(f"Python 核心版本: {sys.version}")

if __name__ == "__main__":
    main()

运行代码有两种常用方式：

• 快速运行：点击编辑器右上角的“播放”三角形图标（Run Python File in Terminal）。VS Code 会自动激活 .venv 并在集成终端中执行脚本。
• 交互式断点调试：在 print("Python 环境配置成功！") 行号左侧单机鼠标左键，打下一个红色的断点圆点。按下键盘 F5 键，选择“Python Debugger” -> “Python File”，程序将暂停在断点处，左侧调试面板将清晰展示局部变量、调用堆栈与监视表达式。

示例终端输出结果：

Python 环境配置成功！
操作系统版本: macOS-14.4.1-arm64-arm-64bit
解释器二进制路径: /Users/username/python_demo/.venv/bin/python
Python 核心版本: 3.12.3 (v3.12.3:f6650f9ad7, Apr  9 2024, 08:18:48) [Clang 15.0.0 (clang-1500.3.9.4)]

五、常见问题排查与避坑指南

即使严格按照步骤操作，不同系统的权限控制与历史残留配置仍可能导致异常。以下是四种高频故障的表现、诱因与确切解决手段：

核心排查对照表

完成上述步骤后，你的计算机上便拥有了一个干净、标准且与项目解耦的现代 Python 编程环境。后续开展任何新项目时，只需在空文件夹中重复“建立目录 -> 创建 .venv -> VS Code 选择解释器”三步，即可获得完全一致的可靠开发体验。