Windows和Mac怎么安装Python并配置VS Code

图 0：Windows 与 macOS 双平台 Python + VS Code 工程化环境全局概览

一、整体流程与环境准备逻辑

许多初学者在配置过程中遇到“命令找不到”、“编辑器无法自动补全”或“依赖库安装后代码无法导入”的问题，根源通常在于混淆了解释器（Python 运行时）与代码编辑器（VS Code 客户端）的职责分工。VS Code 本身只是一个通用的文本编辑器，它不自带 Python 编译运行功能；它需要借助微软官方的 Python 插件，在系统中搜寻已安装好的 python.exe（Windows）或 python3（macOS）可执行文件，并通过语言服务器协议（LSP）为你提供语法高亮、错误检查与终端运行能力。

整个安装配置分为清晰的五个阶段：

1. 底层解释器安装：访问 Python 官网获取对应系统的正式稳定发行版（建议选择 Python 3.10 至 3.12 之间的稳定维护分支）。
2. 系统终端可用性验证：打开命令行工具，确认 python 与 pip 可以全局寻址。
3. 安装 VS Code 与专用扩展：部署官方编辑器并安装 Microsoft 出品的 Python 与 Pylance 插件套件。
4. 工程工作区绑定解释器：建立独立项目文件夹，创建 .venv 虚拟运行环境，避免污染系统全局库。
5. 测试运行与调试闭环：编写 hello.py 测试脚本，验证右键运行、顶部三角按钮执行以及断点调试能力。

图 1：从底层解释器到 VS Code 编辑器协同的五阶段安装调试时序图

二、Windows 10/11 安装 Python 核心步骤

在 Windows 环境下，推荐直接使用 Python 官网提供的 64 位可执行安装包（Windows installer 64-bit）。这一方式相比 Windows 商店版或各类捆绑包更加干净受控。

1. 下载与执行安装程序

打开浏览器访问 Python 官方下载页面（python.org/downloads/windows），下载最新稳定版本的可执行安装程序（例如 python-3.12.x-amd64.exe）。双击运行下载的文件，你将看到一个初始化安装窗口。

勾选完毕后，建议直接点击 “Install Now” 即可开始快速安装；如果你希望将 Python 安装在非系统盘（例如 D:\Python312），可选择“Customize installation”，保留所有默认勾选项（Documentation、pip、tcl/tk 等），在 Advanced Options 中修改安装目录。

2. 禁用 260 字符路径限制（Disable path length limit）

安装进度完成后，安装成功界面会弹出一项提示：“Disable path length limit”（禁用 MAX_PATH 长度限制）。建议点击该选项并允许管理员权限。这可以消除 Windows 传统文件系统对路径长度不得超过 260 字符的历史限制，避免后续在深度嵌套的虚拟环境或 node/python 项目中因路径过长而报错。

3. 验证 Windows 终端识别

关闭安装程序后，按键盘快捷键 Win + R，输入 wt（Windows Terminal）或 cmd 回车，执行以下检测命令：

python --version
pip --version

如果控制台正确打印出形如 Python 3.12.x 以及 pip 24.x from ... 的版本与路径信息，即代表 Windows 底层环境安装彻底完成。

三、macOS 安装 Python 核心步骤

现代 macOS 系统（如 macOS Monterey、Ventura、Sonoma、Sequoia）已不再内置 Python 2，系统自带的 Xcode Command Line Tools 虽然可能提供一个基础的 /usr/bin/python3，但它主要用于系统底层构建，缺少完整的独立管理权限，也不应在其全局目录中频繁随意安装第三方库。

1. 官方安装包部署（推荐初学者）

访问 Python 官网（python.org/downloads/macos/），下载适配合金芯片（Apple Silicon M1/M2/M3/M4）与 Intel 处理器的通用安装包（macOS 64-bit universal2 installer .pkg）。双击安装包，连续点击“继续”并遵循默认设置完成安装。

/Applications/Python\ 3.12/Install\ Certificates.command

2. Homebrew 方式部署（适合习惯命令行的用户）

如果你已经在 Mac 上安装了包管理器 Homebrew，可以通过一行命令完成：

brew install python

安装完成后，Homebrew 会自动将可执行文件软链接至 /opt/homebrew/bin/python3（Apple Silicon 芯片）或 /usr/local/bin/python3（Intel 芯片）。

3. 验证 macOS 终端命令

打开 Mac 自带的“终端”（Terminal）或 iTerm2，执行以下命令：

python3 --version
pip3 --version

四、Windows 与 macOS 环境架构及差异矩阵

为了帮助读者在跨平台协作时不发生概念混淆，下表和架构图全面梳理了两个操作系统在路径结构、默认命令、初始化细节上的实质区别：

图 2：Windows 与 macOS 底层运行环境及关键差异对照矩阵

五、安装 Visual Studio Code 与核心扩展

完成底层的 Python 安装后，接下来部署开发利器 VS Code。

1. 下载与安装 VS Code

前往 VS Code 官方网站（code.visualstudio.com），系统会自动识别你的操作系统：

• Windows 用户：下载 User Installer 64-bit，安装时建议勾选“将‘通过 Code 打开’操作添加到 Windows 资源管理器文件/目录上下文菜单”，便于后续在任何文件夹右键直接启动项目。
• macOS 用户：下载 .zip 压缩包，解压后得到 Visual Studio Code.app，将其拖入“访达 -> 应用程序”（Applications）文件夹中即可完成安装。

2. 安装微软官方 Python 扩展套件

启动 VS Code，点击左侧活动栏的积木图标（Extensions 扩展市场，快捷键 Ctrl+Shift+X / Cmd+Shift+X）。

在搜索框输入 Python，找到由 Microsoft 官方发布的扩展（ID 为 ms-python.python），点击 Install（安装）。该扩展会自动携带安装以下核心协同组件：

• Pylance：高性能语言服务器，提供代码静态分析、类型提示、自动补全与函数签名弹窗。
• Python Debugger：原生调试器，提供断点设置、单步步进、变量观察与调用堆栈分析。

图 3：VS Code 客户端、语言服务器 (Pylance) 与本地 Python 运行时的协同架构

六、在 VS Code 中配置解释器与工程化虚拟环境

切忌直接在无项目的孤立窗口中写代码。现代 Python 开发的标准化做法是：以文件夹为工作区，并在每个工作区内配置专属的虚拟环境（venv）。这样可以使当前项目的依赖库与系统全局环境彻底隔离，避免版本冲突。

1. 打开或创建工作目录

在你的电脑上创建一个专门用于存放代码的目录（例如 D:\Projects\py-demo 或 ~/Projects/py-demo）。打开 VS Code，点击菜单栏的 File -> Open Folder...（文件 -> 打开文件夹），选中该目录并进入。

2. 创建并激活虚拟环境（.venv）

在 VS Code 顶部菜单选择 Terminal -> New Terminal（终端 -> 新建终端），此时编辑器底部会调出集成终端。输入以下标准命令生成虚拟环境：

# Windows 环境执行：
python -m venv .venv

# macOS 环境执行：
python3 -m venv .venv

执行完成后，左侧项目资源管理器中会出现一个名为 .venv 的文件夹。此时 VS Code 会智能检测到新虚拟环境，通常会在右下角弹出提示：“We noticed a new environment has been created. Do you want to select it for the workspace folder?”，点击 Yes 即可。

3. 手动绑定解释器（Select Interpreter）

如果没有弹出提示，你可以随时通过以下标准化方式手动指定解释器：

1. 按下快捷键 Ctrl + Shift + P（Windows）或 Cmd + Shift + P（Mac）调出命令面板。
2. 在输入框中键入 Python: Select Interpreter 并按回车。
3. 在候选列表中，优先选择带有 ('.venv': venv) 标记的推荐项（路径形如 ./.venv/Scripts/python.exe 或 ./.venv/bin/python）。

绑定成功后，观察 VS Code 最底部状态栏右下角，将明确显示 Python 3.12.x ('.venv': venv)，代表工作区解释器绑定成功。

七、编写测试脚本与多模式运行验证

环境配置完毕后，通过编写一个具备环境自检功能的测试脚本，验证代码补全与执行闭环。

1. 编写 hello.py 脚本

在 VS Code 左侧文件树中点击“新建文件”图标，命名为 hello.py，录入以下内容：

import sys
import os

def check_environment():
    print("=" * 45)
    print("Python 与 VS Code 开发环境连通测试成功！")
    print(f"当前 Python 版本: {sys.version.split()[0]}")
    print(f"当前解释器路径: {sys.executable}")
    print(f"当前工作目录: {os.getcwd()}")
    print("=" * 45)

if __name__ == "__main__":
    check_environment()

2. 运行脚本的两种常用方式

• 方式一：编辑器右上角三角运行键（推荐日常使用）
  打开 hello.py 文件时，编辑器右上角会出现一个形如播放键的 “Run Python File” 图标。点击它，VS Code 会自动在下方集成终端中激活当前绑定的虚拟环境并执行当前文件。
• 方式二：集成终端原生指令执行
  直接在下方的终端中键入 python hello.py（激活虚拟环境后双平台均直接使用 python 命令）。

3. 期望的验证输出

执行后，如果下方控制台打印出如下结构化信息，特别注意当前解释器路径包含 .venv 目录字段，即证明当前代码运行在独立的工程虚拟环境中：

=============================================
Python 与 VS Code 开发环境连通测试成功！
当前 Python 版本: 3.12.3
当前解释器路径: /Users/username/Projects/py-demo/.venv/bin/python
当前工作目录: /Users/username/Projects/py-demo
=============================================

八、常见问题排查与排错决策指南

在实际搭建过程中，初学者常因操作系统权限、网络证书或环境上下文混乱遇到以下典型问题。请对照下方决策矩阵进行针对性排查：

图 4：Python 与 VS Code 典型故障定位与即时修复决策树

问题 1：Windows PowerShell 激活环境报错“禁止运行脚本”

错误表现：在 Windows 集成终端执行 activate 脚本时，红色报错提示：无法加载文件 .venv\Scripts\Activate.ps1，因为在此系统上禁止运行脚本。
产生原因：Windows 为安全考虑，默认将 PowerShell 的执行策略设置为 Restricted（受限模式）。
解决方法：点击“开始菜单”，搜索 PowerShell，右键选择“以管理员身份运行”，输入以下命令并按 Y 确认：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

设置完成后，重新打开 VS Code 即可正常激活脚本。

问题 2：macOS 执行 pip 安装报“SSL: CERTIFICATE_VERIFY_FAILED”

错误表现：使用 pip install 安装第三方包时，频繁抛出 [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate。
产生原因：macOS 官方包自带的 OpenSSL 并不自动复用 macOS 系统 Keychain 的根证书。
解决方法：在终端执行 Python 自带的证书更新脚本。若安装的是 Python 3.12，直接在终端粘贴运行：

/Applications/Python\ 3.12/Install\ Certificates.command

等待终端打印“Installing certificates... Successfully installed”后，重新执行 pip 命令即可恢复正常。

问题 3：VS Code 代码出现黄色波浪线，提示“Import 'xxx' could not be resolved”

错误表现：明明已经在终端通过 pip 安装了第三方库（例如 requests），但在 import requests 处依然画黄线报警，且运行报错找不到模块。
产生原因：终端安装依赖的 Python 环境与 VS Code 右下角选中的解释器不一致。例如你在系统全局安装了库，但 VS Code 绑定的是 .venv，或者反之。
解决方法：确保 VS Code 右下角选中的解释器正是你执行 pip 的环境。如果使用 .venv，请在 VS Code 集成终端中先执行激活命令，再执行 pip install requests，此时代码提示与运行环境即可完全统一。

九、总结

总结起来，无论是 Windows 还是 macOS，搭建现代化 Python 开发环境的核心原则只有两句话：

一是在系统层面确保官方解释器安装完备、PATH 变量可被全局终端正确寻址；二是在 VS Code 层面通过官方扩展建立对解释器的显式绑定，并在具体项目中养成使用 .venv 虚拟环境的工程化习惯。

遵循这套规范，开发环境不仅整洁透明，而且在后续安装科学计算库、Web 开发框架或与团队跨平台协作时，都能彻底免受环境污染与版本错乱的困扰。