跨平台配置 VSCode 全指南（Python开发 + Git + Codex AI编程助手）

Ne0inhk

21 Mar 2026 — 8 min read

适用对象：Windows / macOS / Linux 用户，Python 开发者，使用 Git 进行版本管理，并希望在 VSCode 中集成 AI 编程助手（Codex）。
目标：配置稳定、可复现、可迁移的开发环境，避免“能用但不可靠”的做法。

声明：本教程由豆包和ChatGPT协助完成。

一、基础环境准备：VSCode下载与安装

1. 下载VSCode（跨平台通用）

访问VSCode官方下载页：https://code.visualstudio.com/Download
根据系统选择对应安装包：
- Windows：下载「Windows Installer (.exe)」（64位），安装时建议勾选「Add to PATH」（关键）
- Mac：下载「Mac Universal」（适配Intel/M1/M2），解压后将VSCode拖入「应用程序」文件夹

2. 首次启动基础配置

启动VSCode后，先完成基础设置：

中文语言包安装：
1. 按下 Ctrl+Shift+P（Windows）/ Cmd+Shift+P（Mac）打开命令面板
2. 输入 Configure Display Language，回车
3. 选择「Install additional languages…」，搜索「Chinese (Simplified)」，安装后重启VSCode
验证安装：重启后界面为中文，说明基础安装成功

二、Git与.gitignore配置（跨平台通用）

1. 安装Git（前置条件）

Windows：下载 Git for Windows：https://git-scm.com/download/win，安装默认选项即可（可勾选「Git Bash Here」）
Mac：终端执行 xcode-select --install 安装Xcode命令行工具（包含Git），或用Homebrew：brew install git
验证：终端/CMD输入 git --version，显示版本号即说明安装成功

2. VSCode集成Git

打开VSCode，进入「设置」（Ctrl+, / Cmd+,）
搜索「git.path」，确认 VSCode 能找到 git（多数情况下无需手动设置）。如确需指定：
- Windows：C:\Program Files\Git\bin\git.exe
- Mac：/usr/bin/git
配置提交身份（建议）：
- git config --global user.name "你的用户名"
- git config --global user.email "你的邮箱"

3. .gitignore配置（核心）

.gitignore用于忽略不需要提交的文件（如环境配置、缓存、本地配置文件）。

步骤1：创建.gitignore文件

在项目根目录新建文件，命名为 .gitignore（注意开头的点）
针对Python + micromamba环境，添加以下内容：

# Python通用忽略 __pycache__/ *.py[cod] *$py.class *.so .Python build/ dist/ *.egg-info/ .eggs/ wheels/ pip-wheel-metadata/ # Micromamba / Conda（注意：一般不建议把环境目录放在项目内） .micromamba/ .mamba/ conda-meta/ pkgs/ envs/ .micromamba-lock.json .condarc # 本地配置文件（自定义） local_config.py .env .env.local config/secret/ # VSCode本地配置（团队协作时可按需选择是否忽略） .vscode/settings.json .vscode/launch.json .vscode/extensions.json .vscode/*.log # 系统文件 .DS_Store Thumbs.db

步骤2：让VSCode识别.gitignore

保存.gitignore文件后，VSCode会自动应用规则
验证：创建一个 local_config.py 文件，Git面板中不应默认纳入提交

三、Micromamba环境配置（跨平台）

Micromamba 是 Conda 的轻量替代方案，适合做可迁移的 Python 环境管理。

备注：关于 Windows 下 micromamba 的完整配置（含国内源、PowerShell Hook、可拷贝部署等进阶功能），可参考：
https://blog.ZEEKLOG.net/knicknock/article/details/156064291

1. 安装Micromamba

Windows：
1. 下载 micromamba（mamba-org releases）：https://github.com/mamba-org/mamba/releases
2. 将 micromamba.exe 放到一个固定目录（例如 C:\micromamba\bin\），并加入 PATH
3. 重启终端，执行 micromamba --version 验证
Mac：
1. 终端执行：curl micro.mamba.pm/install.sh | bash
2. 按提示执行 source ~/.bashrc（bash）或 source ~/.zshrc（zsh）
3. 验证：micromamba --version

2. VSCode集成Micromamba环境

步骤1：创建Micromamba环境（示例）

micromamba create -n python312 python=3.12 -y micromamba activate python312

步骤2：VSCode关联环境

打开VSCode，安装「Python」插件（微软官方，下文会详细讲）
按下 Ctrl+Shift+P / Cmd+Shift+P，输入「Python: Select Interpreter」
在列表中选择 micromamba 环境对应的 Python 解释器（路径以你实际安装为准）
验证：打开 VSCode 终端后，确保运行 python -V 输出为对应版本（如 3.12.x）

3. VSCode启动项配置（自动激活环境，可选）

更推荐的做法：让终端本身支持 micromamba activate（通过 shell hook），而不是把激活命令硬编码到 VSCode 启动参数里。

Windows（PowerShell）：请参考给出的 Windows 进阶教程（含 hook 细节）。

macOS / Linux（zsh 举例）：

micromamba shell hook -s zsh -p ~/micromamba > ~/.zshrc_micromamba echo'source ~/.zshrc_micromamba'>> ~/.zshrc source ~/.zshrc

四、Python相关插件安装

1. 核心插件列表（按优先级排序）

插件名称	开发者	核心功能	安装方法
Python	Microsoft	基础Python支持（调试、环境管理）	扩展市场搜索「Python」安装
Pylance	Microsoft	智能补全、类型检查、代码导航	通常随 Python 插件推荐安装
Black Formatter	Microsoft	代码格式化（PEP8风格）	扩展市场搜索安装
isort	Microsoft	导入排序	扩展市场搜索安装
GitLens	GitKraken	Git增强（提交记录、行级注释）	扩展市场搜索安装

2. 插件配置（优化Python开发体验）

打开 settings.json（Ctrl+, / Cmd+, → 右上角「打开设置(JSON)」），添加：

{"python.analysis.typeCheckingMode":"basic","python.analysis.autoImportCompletions":true,"editor.formatOnSave":true,"editor.codeActionsOnSave":{"source.organizeImports":"explicit"},"python.analysis.completeFunctionParens":true,"python.analysis.diagnosticSeverityOverrides":{"reportMissingImports":"warning","reportUnusedVariable":"information"}}

五、OpenAI Codex（ChatGPT）插件安装与使用

这一节按 OpenAI 官方 Codex 页面与 Codex 文档更新校正：Codex 是 OpenAI 的 coding agent，支持在 IDE/终端使用，并且可通过 ChatGPT 登录（订阅权益）或 API Key（按量计费）。
官方也提供 Codex VS Code 扩展 与 Codex CLI。

重要备注（国内网络）

Codex 扩展/CLI 登录可能需要访问 OpenAI/ChatGPT 域名；网络受限时可能出现登录回调失败、超时等问题。
若出现浏览器登录回调（localhost）被阻断，可优先使用文档提供的设备码登录（实验性）或 API Key 登录等替代路径。
网络环境：已配置科学上网（节点优选美丽国），可正常访问OpenAI官网

1. 前置条件

Codex 支持两种登录方式：

ChatGPT 登录（订阅权益）：适用于 ChatGPT Plus / Pro / Business / Edu / Enterprise 用户（使用订阅包含的 Codex 使用额度）。
API Key 登录（按量计费）：通过 OpenAI Platform 的 API Key 使用，按 API 定价计费。

补充：Codex cloud（云端委派执行）需要使用 ChatGPT 登录。CLI 与 IDE 扩展两种方式都支持 ChatGPT 或 API Key 登录。

2. 安装「Codex」VS Code 扩展（官方）

打开 VSCode 扩展市场（Ctrl+Shift+X / Cmd+Shift+X）
搜索 Codex（OpenAI 的 Codex 扩展），安装完成后左侧活动栏会出现 Codex 图标
重启 VSCode（若未显示）

官方文档说明：Codex IDE 扩展可用于 VS Code 及其部分 fork（如 Cursor、Windsurf）。扩展主要在 macOS / Linux 可用；Windows 支持为“实验性”，更建议在 WSL 工作区中使用并参考官方 Windows 指南。

3. 登录方式（ChatGPT 或 API Key）

安装扩展后会提示登录：

用 ChatGPT 账号登录：会打开浏览器完成登录，随后返回 token 给扩展
用 API Key 登录：在扩展/CLI 中粘贴 API Key（按量计费）

安全提示：Codex 会缓存登录凭据（可能在 ~/.codex/auth.json 或系统凭据库），请像对待密码一样对待，不要提交到 Git，也不要发到群里。

4. Chat 模式与 Agent 模式（以及更高权限模式）

Codex IDE 扩展支持不同的“批准/自治”模式：可在 Chat、Agent、以及更高权限的 Agent 模式之间切换（具体命名以扩展 UI 为准）。

Chat（对话）：适合解释、问答、生成小段代码
Agent（代理）：适合多步骤任务（读代码、改文件、运行命令/测试）
更高权限的 Agent 模式：适合希望它更自动化地执行（需你对权限更谨慎）

使用建议：教学/团队环境建议默认 Chat 或低权限 Agent，涉及运行脚本、改大量文件时再逐步提高权限。

5. Codex CLI（可选）

官方页面给出 Codex CLI 的安装方式（Node 环境）：

npm i -g @openai/codex

CLI 同样支持 ChatGPT 登录或 API Key 登录，并与 IDE 扩展共享缓存凭据（登出任一端会影响另一端）。

六、常见问题与兼容性解决方案

1. Mac下Micromamba环境无法被VSCode识别

解决方案：确保 shell hook 配置正确并重启终端与 VSCode：

micromamba shell hook install -s zsh

2. Windows 下 Codex 扩展体验不佳

官方说明 Windows 支持为实验性，更推荐在 WSL 工作区中使用并参考 Windows 指南。

3. Pylance补全失效

解决方案：更新 Pylance 插件，执行「Python: Restart Language Server」

4. 终端登录回调失败（常见于受限网络/远程环境）

解决方案：优先尝试设备码登录（实验性）或 API Key 登录；也可参考文档的“转发 localhost 回调”等方案。

总结

核心关键点回顾：

跨平台配置核心：VSCode 基础安装建议加入 PATH；Git / Python 解释器路径尽量通过自动发现或选择解释器完成，避免硬编码；
本地环境管理：.gitignore 需覆盖环境缓存、本地配置与密钥；Micromamba 建议通过 shell hook 正常激活；
Codex 使用：官方提供 Codex VS Code 扩展与 Codex CLI；支持 ChatGPT 登录（订阅权益）或 API Key（按量计费）；Windows 支持为实验性，优先考虑 WSL。

其他需要注意的点：

定期更新VSCode和插件（Ctrl+Shift+P → 「Extensions: Check for Extension Updates」）
为不同项目创建独立的 .vscode/settings.json，实现个性化配置
保护好登录凭据与 API Key：不要写进仓库，不要放进公开的 settings.json（更推荐环境变量或凭据库）