安装顺序： VSCode→ Git → Docker Desktop → uv → ccswitch

全程 Windows 10/11 64 位，每装完一个建议重启一次终端；Docker 安装前重点检查 CPU 虚拟化！

通用原则：软件路径不要中文、不要空格

一、第一步：安装 VS Code

1. 下载

https://code.visualstudio.com/Download 下载 Windows User Installer（64 位）

2. 安装【必勾选项】

许可协议 → 下一步；自定义安装路径（建议放 D 盘） 来到「选择附加任务」页面，全部勾选： ✅ 添加到 PATH（重启 shell 生效） ✅ 注册为受支持文件编辑器 ✅ 添加 “通过 Code 打开” 右键菜单 ✅ 创建桌面快捷方式

下一步 → 安装。

3. VS Code 安装必备扩展（打开 VSCode 扩展面板 Ctrl+Shift+X）

1. Python（Microsoft 官方）【必装】 Python 语言支持、代码补全、调试、解释器选择
2. Ruff【强烈推荐，uv 配套】 极速代码格式化 + 静态检查，替代 flake8/isort
3. Pylance（随 Python 扩展自动附带）
4. 可选：Python Debug Console、indent-rainbow

二、第二步：安装 Git（最先装，VSCode 依赖 Git）

1. 下载

官网：https://git-scm.com/download/win 下载 64-bit Git for Windows Setup

2. 安装关键勾选（一路下一步，重点看这里）

1. 运行安装包 Git‑xxx‑64‑bit.exe

点击 Next 进入下一步

2. Select Destination Location（安装路径）

• 默认：C:\Program Files\Git
• 想改到 D 盘就点 Browse，路径不要中文、不要空格
• 选好后 → Next

3. Select Components（组件勾选）

✅ 保持默认勾选即可：

• Git Bash Here
• Git GUI Here
• Git LFS
• Associate .git* configuration files ...

不要额外乱加勾选，直接 Next

4. Choosing the default editor used by Git（选择编辑器）

下拉选择 Use Visual Studio Code as Git's default editor

绑定 VS Code，提交写注释更方便 → Next

5. Adjusting your PATH environment（关键页面！必选这个）

选择： Git from the command line and also from 3rd‑party software

含义：把 Git 加入系统环境变量，PowerShell、CMD、VSCode 终端都能识别git命令 → Next

6. Choosing the SSH executable

默认：Use bundled OpenSSH（自带 SSH，不用系统 OpenSSH） 保持不动 → Next

7. Choosing HTTPS transport backend

默认：Use the native Windows Secure Channel library 保持默认 → Next

8. Configuring the line ending conversions（换行符设置，开发必配）

选择： Checkout Windows‑style, commit Unix‑style line endings

Windows 检出 CRLF，提交给 Git 仓库用 LF，跨平台兼容 WSL / Docker / Linux 项目 → Next

9. Configuring the terminal emulator to use with Git Bash

选择：Use MinTTY (the default terminal of MSYS2) → Next

10. Choose the default behavior of git pull

默认：Fast‑forward or merge 保持不变 → Next

11. Choose a credential helper（凭证管理器）

✅ Git Credential Manager（自动保存 Github 账号密码 / 令牌，强烈保留） → Next

12. Configuring extra options（额外功能）

全部保持默认勾选：

• Enable file system caching
• Enable symbolic links → Next

13. Experimental options（实验性功能）

两个复选框全部不要勾选 直接点 Install

14. 安装结束

取消掉：View Release Notes（不需要看更新日志） ✅ 勾选 Launch Git Bash（可选） 点击 Finish

3. 验证 & 基础配置

打开 PowerShell / Git Bash

git --version

出现版本号即成功。

配置全局用户名邮箱（和你的 GitHub 账号一致）

git config --global user.name "你的用户名"
git config --global user.email "你的github注册邮箱"

4. 可选：生成 SSH 密钥（方便拉取 Github，不用每次输账号密码）

ssh-keygen -t ed25519 -C "你的github邮箱"

连续三次回车（不设置密钥密码） 查看公钥：

cat ~/.ssh/id_ed25519.pub 

复制密钥（ssh开头，邮箱结尾），去 GitHub 设置 → SSH and GPG keys 粘贴添加。

三、第三步：安装 Docker Desktop ⚠️前置条件非常重要

前置检查（必须完成，否则 Docker 启动失败）

1. Ctrl+Shift+Esc 打开任务管理器 → 性能 → CPU，查看虚拟化：已启用

• 如果显示禁用：重启电脑，进 BIOS 开启 Intel VT-x / AMD-V

1. 以管理员身份打开 PowerShell，一键启用 WSL2

wsl --install

执行完成后重启电脑！

1. 下载 Docker Desktop

https://www.docker.com/products/docker-desktop/

2. 安装设置

双击安装包 ✅ Use WSL 2 instead of Hyper-V（必勾选） ✅ Add shortcut to desktop 点击 OK 开始安装，完成后重启电脑。

3. 首次启动配置

1. 打开 Docker Desktop，接受协议
2. 设置（齿轮）→ General：保持【Use the WSL 2 based engine】开启
3. Resources → WSL Integration，启用对应子系统
4. 【国内优化】Settings → Docker Engine，添加镜像加速器（解决拉镜像慢）

4. 验证

新开终端运行

docker --version
docker compose version

四、第四步：安装 uv（Python 包管理）

推荐方式：PowerShell 管理员执行一键安装

powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装程序自动写入环境变量。

验证（必须新开 PowerShell 窗口）

uv --version

输出版本号代表成功。

安装python全局基础解释器（uv和全局python全局基础解释器放在 C 盘用户目录,后续项目文件的虚拟环境放在D盘）

uv python install 3.12

五、第五步：安装 CC Switch（模型 API 切换工具）

1. 下载地址

前往 Github Releases：https://github.com/zuoliangyu/cc-switch/releases 下载：CC-Switch-vxxx-Windows.msi（安装版，推荐）

2. 安装要点

1. 双击 msi，如 Windows 拦截：更多信息 → 仍要运行
2. 自定义路径，路径不能有中文、空格
3. ✅勾选：添加到系统 PATH、桌面快捷方式
4. 完成启动 CC Switch

3. 迁移配置

如果你旧电脑导出过供应商配置：打开 CC Switch → 导入配置文件，直接恢复 API 密钥与模型设置。

📌整套安装完成后，新电脑标准开发上线流程

1. Git Bash 测试 SSH 连通 Github：ssh -T git@github.com
2. 新建项目文件夹，git clone xxx.git拉取代码
3. 手动拷贝旧电脑备份的 .env、私有配置文件（.gitignore 内文件）
4. 项目目录执行 uv venv && uv sync 重建 Python 环境
5. 启动 Docker Desktop，执行docker compose up -d启动容器
6. VS Code 打开项目，选择 uv 创建的.venv内 Python 解释器

⚠️高频踩坑清单

1. 安装完工具不重启终端，命令找不到（PATH 未加载）
2. Docker 没开启虚拟化、未安装 WSL2，启动报错
3. uv/ccswitch 安装路径带中文，程序异常
4. 尝试复制.venv、Docker 镜像文件夹跨电脑迁移，出现路径报错
5. Github 拉代码忘记拷贝.env 密钥，本地运行缺少参数