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

一、Python 运行机制与环境准备核心概念

初次接触 Python 开发时，容易把“写代码的软件”与“执行代码的程序”混为一谈。理解两者分工有助于快速排查后续可能遇到的路径和解释器识别问题：

• Python 解释器（Python Interpreter）：负责把以 .py 为后缀的纯文本源码解析为字节码，并在本地虚拟机中执行。无论在哪个操作系统，执行 Python 代码都必须有对应的解释器可执行文件（Windows 下为 python.exe，macOS 下通常为 python3）。
• 环境变量 PATH 的核心作用：在终端中输入 python 命令时，操作系统本身并不知道该程序保存在哪个具体磁盘目录下。操作系统会依次在系统变量 PATH 中列出的所有文件夹里寻找同名程序。如果 Python 的安装目录被登记到了 PATH 中，终端就能直接运行；如果没有登记，就会提示找不到命令。
• 代码编辑器 VS Code：Visual Studio Code 是一个轻量级编辑器，自身并不内置 Python 执行引擎。它通过安装 Microsoft 官方的 Python 插件，检测系统安装好的 Python 路径，将用户编写的代码发送给本地解释器执行，并把结果实时回显在内置终端中。

二、Windows 平台 Python 安装与环境验证

在 Windows 10 或 Windows 11 下安装 Python，最稳妥的方式是直接使用官方安装包。整个过程的关键在于正确勾选环境变量开关。

1. 下载官方安装程序

打开浏览器访问 Python 官方网站（python.org），将鼠标悬停在导航栏的 Downloads 菜单上，网页会自动推荐适用于 Windows 的最新稳定版本（例如 Python 3.12.x）。点击黄色按钮下载 64 位安装程序（文件名称通常为 python-3.12.x-amd64.exe）。

2. 运行安装程序与关键选项选择

双击运行下载好的安装程序。在弹出的首个界面底部，有两个非常关键的多选框，请务必仔细确认：

对于初学者，确认勾选了 PATH 选项后，直接点击界面中央的 “Install Now” 即可进入自动化安装。如果希望将 Python 安装在指定目录（例如非系统盘），也可以选择 “Customize installation” 自定义路径，但请确保安装路径中不包含中文字符或特殊符号。

3. 解除路径长度限制（Disable path length limit）

安装进度完成后，成功界面中可能会出现一行蓝色文字按钮：“Disable path length limit”（禁用 MAX_PATH 长度限制）。推荐直接点击该选项并允许管理员权限。Windows 传统规范中单个文件路径上限为 260 个字符，现代 Python 项目安装复杂第三方库时极易超出该限制，解除限制可以预防后续潜在的构建报错。

4. 打开终端验证安装

安装完成后，需要验证系统是否能够识别 Python 指令：

1. 按下键盘上的快捷键 Win + R，在运行窗口中输入 cmd 并回车，打开命令提示符。
2. 输入以下命令查看 Python 版本：

python --version

示例输出：

Python 3.12.4

继续检查附带的包管理工具 pip：

pip --version

示例输出：

pip 24.0 from C:\Users\Username\AppData\Local\Programs\Python\Python312\Lib\site-packages\pip (python 3.12)

若两行指令均能正常输出版本号，说明 Windows 系统的基础 Python 解释器环境已准备就绪。

三、macOS 平台 Python 安装与多版本管理

macOS 系统的环境机制与 Windows 有所不同。现代 macOS 系统（如 macOS Monterey、Ventura、Sonoma 等）移除了旧版的 Python 2，但某些系统开发工具依然包含精简版运行环境。开发者必须建立独立的 Python 运行时，切勿对系统级预置目录进行任何修改。

方式一：官方 PKG 安装包安装（推荐入门）

访问 python.org/downloads/macos/，下载适用于 macOS 的 macOS 64-bit universal2 installer。该安装包同时支持 Intel 架构与 Apple Silicon（M1/M2/M3/M4 系列芯片）。

下载后双击 .pkg 文件，按照安装引导一路点击“继续”并输入 Mac 开机密码。安装器会自动将 Python 框架安装在 /Library/Frameworks/Python.framework 目录下，并在系统的 /usr/local/bin 中自动创建 python3 与 pip3 的符号链接。

安装完成弹出文件夹后，建议双击运行其中的 Install Certificates.command 脚本，它会自动配置 Python 使用的标准 SSL/TLS 根证书，避免后续在通过代码请求 HTTPS 网络时出现证书校验失败。

方式二：使用 Homebrew 包管理器安装（适合开发者）

如果你的 Mac 已经配置了 Homebrew，可以通过终端单条命令直接完成安装：

brew install python

在 Apple Silicon 芯片的 Mac 上，Homebrew 会将可执行文件放置在 /opt/homebrew/bin/python3；在 Intel 芯片的 Mac 上则放置在 /usr/local/bin/python3。Homebrew 的优势在于未来只需执行 brew upgrade python 即可一键更新版本。

终端环境验证

打开 macOS 的“终端”（Terminal）应用，输入以下命令核验：

python3 --version
which python3
pip3 --version

示例输出：

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

在 macOS 终端中，请习惯使用 python3 和 pip3 命令，这能明确指定调用我们新安装的独立环境，避免与系统遗留工具混淆。

四、VS Code 安装与核心 Python 扩展配置

底层解释器安装完毕后，接下来配置日常编写代码的图形界面工具——Visual Studio Code。

1. 获取并安装 VS Code

访问 VS Code 官方网站（code.visualstudio.com），下载对应系统的安装包：

• Windows 用户：下载 Windows x64 User Installer，安装时建议勾选“添加到 PATH”以及“将‘通过 Code 打开’操作添加到 Windows 资源管理器文件上下文菜单”。
• macOS 用户：下载 Universal 版本的压缩包，解压后得到 Visual Studio Code.app，将其直接拖拽至系统的 “应用程序”（Applications） 文件夹中即可。

2. 安装 Python 核心扩展

启动 VS Code。点击左侧活动栏的积木图标（快捷键 Windows: Ctrl + Shift + X，Mac: Cmd + Shift + X）进入扩展商店（Extensions）。

在顶部搜索框中输入 Python。在搜索结果中找到由 Microsoft 官方发布、下载量数千万的同名插件，点击 Install 按钮。该扩展会自动捆绑安装 Pylance（高性能语言分析服务），为代码提供智能补全、类型推断、跳转到定义以及实时语法错误高亮提示。

3. 选择与绑定 Python 解释器（Select Interpreter）

VS Code 需要明确当前工程使用哪个具体的 Python 版本。配置方法非常直接：

1. 使用快捷键调出全局命令面板：Windows 用户按 Ctrl + Shift + P，macOS 用户按 Cmd + Shift + P。
2. 在弹出的搜索框中输入：Python: Select Interpreter 并按回车。
3. VS Code 会自动扫描系统中已安装的所有 Python 运行时。在下拉列表中，点击选择刚刚安装的 Python 3.12 即可。

选择完成后，VS Code 窗口最底部的状态栏右下角会清晰显示当前选中的 Python 版本（例如 Python 3.12.x 64-bit）。点击该状态栏标签也可以随时重新唤出解释器切换菜单。

五、编写首个脚本与项目虚拟环境管理

现在我们可以通过创建一个实际项目文件夹来测试整个开发链路的连通性。

1. 新建工作区与测试文件

在电脑中新建一个空文件夹（例如命名为 learn_python）。在 VS Code 中点击菜单栏 File -> Open Folder... 打开该文件夹。

在左侧资源管理器中点击“新建文件”图标，创建一个名为 app.py 的文件，并粘贴以下测试代码：

import sys
import platform

def test_environment():
    print("=" * 45)
    print("Python 与 VS Code 运行环境配置成功！")
    print("=" * 45)
    print(f"操作系统平台: {platform.platform()}")
    print(f"当前 Python 版本: {platform.python_version()}")
    print(f"解释器执行路径: {sys.executable}")

if __name__ == "__main__":
    test_environment()

2. 运行代码的两种常用方式

代码保存后（快捷键 Ctrl + S 或 Cmd + S），有两种方式执行程序：

• 方式 A：图形化按钮一键运行。点击编辑器右上角的三角形“运行 Python 文件”（Run Python File）按钮。VS Code 会在底部自动唤起内置集成终端，并自动拼接正确的命令来执行脚本。
• 方式 B：集成终端手动执行。使用快捷键 Ctrl + `（反引号）打开终端，在当前项目路径下输入：
  Windows 平台：python app.py
  macOS 平台：python3 app.py

示例运行结果：

=============================================
Python 与 VS Code 运行环境配置成功！
=============================================
操作系统平台: macOS-14.5-arm64-arm-64bit
当前 Python 版本: 3.12.4
解释器执行路径: /Library/Frameworks/Python.framework/Versions/3.12/bin/python3

3. 项目标准实践：创建独立虚拟环境（venv）

随着学习深入，不同的项目可能需要依赖不同版本的第三方包。如果所有库都安装在全局环境中，容易引发版本冲突。Python 原生内置了虚拟环境管理模块 venv。

在 VS Code 集成终端中，进入项目根目录执行以下命令创建名为 .venv 的虚拟环境：

Windows 系统命令：

python -m venv .venv
.venv\Scripts\activate

macOS 系统命令：

python3 -m venv .venv
source .venv/bin/activate

激活成功后，终端命令行最前端会出现 (.venv) 标记。同时，VS Code 会弹出提示：“已检测到新创建的虚拟环境，是否要为其选择此环境？”，点击“是”（Yes），编辑器便会将后续的代码运行、语法提示和包安装自动锁定在当前项目的独立容器内。

六、常见配置报错与排查指南

在初次搭建环境过程中，可能遇到几类常见问题，通常只需按以下步骤逐一核实即可解决。

1. 报错：“'python' 不是内部或外部命令”或“command not found”

发生原因：操作系统在环境变量 PATH 中没有找到名为 python 的可执行文件。这通常是因为在 Windows 安装向导中漏勾了“Add python.exe to PATH”。

解决方法：重新运行 Python 官网下载的安装程序，在弹窗中选择 Modify（修改），勾选环境注册选项并点击 Next 完成更新；或者手动在 Windows 搜索框搜索“编辑系统环境变量” -> 点击“环境变量” -> 在用户变量的 Path 中追加 Python 的安装路径及其下的 Scripts 目录。对于 macOS 用户，检查终端中是否误敲了 python 而非 python3。

2. Windows PowerShell 报错：“在此系统上禁止运行脚本”

发生原因：在 Windows 下执行虚拟环境的 activate 脚本时，PowerShell 默认的安全执行策略（ExecutionPolicy）为 Restricted，阻止运行未经签名的自定义脚本。

解决方法：在 Windows 搜索框中找到“PowerShell”，右键选择“以管理员身份运行”，输入以下命令并将策略调整为仅信任本地脚本：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

按键盘上的 Y 确认回车，随后重启 VS Code 即可顺畅激活虚拟环境。

3. VS Code 无法自动检测到解释器，右下角提示“Select Interpreter”

发生原因：Python 安装在非标准路径，或者 VS Code 启动时底层进程尚未刷新系统环境变量缓存。

解决方法：完全重启 VS Code。若仍未列出，按 Ctrl+Shift+P（Mac 下 Cmd+Shift+P）输入 Python: Select Interpreter，选择第一项 “Enter interpreter path...”（输入解释器路径），随后点击 “Find...” 浏览磁盘，直接选中 Python 安装目录下的 python.exe（Windows）或 python3（Mac）二进制文件即可完成手动指定。

4. macOS 首次运行提示需要安装“Command Line Developer Tools”

发生原因：macOS 终端在调用某些底层编译链或 Homebrew 组件时需要基础开发者工具支持。

解决方法：当系统弹出提示框时，直接点击“安装”按钮，或者在终端中手动输入：

xcode-select --install

等待几分钟下载完成后，再执行 python3 相关命令即可正常工作。

七、配置自查清单与总结

完成上述所有步骤后，可以通过以下四个维度的核验标准，确认本地 Python 与 VS Code 开发环境是否达到标准的就绪状态。

通过理解 Python 解释器的系统路径机制，并配合 VS Code 的官方插件管理，无论是 Windows 还是 macOS 平台，都能获得一致、稳定且易于维护的代码编写与调试体验。在日常开发中，建议为每个独立项目建立对应的虚拟环境，保持基础开发环境的整洁与可靠。