编辑器配置:把 VS Code 调成顺手的 AI 开发环境

编辑器配置:把 VS Code 调成顺手的 AI 开发环境

本节摘要:你的编辑器是你的副驾驶——花 20 分钟把它配好,它就不会再给你添堵,反而会开始替你干活。接下来几千个小时,你会在编辑器里写 Python、跑 Notebook、调训练循环、SSH 进 GPU 机器。配置糟糕的编辑器会把每个会话变成摩擦:没有自动补全、没有类型提示、没有内联报错、要手动格式化、终端体验别扭。本节带你一次配好 VS Code 的 AI 开发五要素(基础编辑器 → 扩展 → AI 专属设置 → 终端集成 → 远程开发),装上 Python、Pylance、Jupyter、GitLens、Remote-SSH、Ruff 这些必备扩展,开启保存即格式化、类型检查、Notebook 输出滚动,并用 Remote-SSH 把远程 GPU 机器当成本地来编辑调试。最后顺带评估 Cursor、Windsurf、Neovim 这些替代方案的取舍。

对应原课程:Phase 00 · Lesson 08 · editor-setup(原英文 phases/00-setup-and-tooling/08-editor-setup/docs/en.md)。前置:第 01 节「开发环境」。

学习目标

阅读完本节,你应当能够:

1. 安装 VS Code 与必备扩展(Python、Jupyter、linting、Remote-SSH)。
2. 配置保存即格式化、类型检查、Notebook 输出滚动这些 AI 工作流关键设置。
3. 用 Remote-SSH 在远程 GPU 机器上编辑与调试代码,体验与本地无异。
4. 评估 Cursor、Windsurf、Neovim 等编辑器替代方案的取舍。

一、问题与直觉

接下来几千个小时,你会泡在编辑器里:写 Python、跑 Notebook、调训练循环、SSH 进 GPU 机器。配置糟糕的编辑器会让每次会话都充满摩擦——没有自动补全、没有类型提示、没有内联报错、要手动格式式、终端体验别扭。

正确配置只要 20 分钟,跳过它则每天损失 20 分钟。

AI 工程的编辑器配置需要五样东西,自底向上叠加:

💡 这五层和第 01 节的开发环境四层栈一脉相承:先把基础编辑器装好,再装扩展,再调设置,再管终端,最后接通远程。任何一层缺位都会拖累整体体验。

二、从零实现

Step 1 装 VS Code

推荐 VS Code——免费、跨平台、有一流的 Jupyter Notebook 支持,扩展生态覆盖 AI 工作所需的一切。从 code.visualstudio.com 下载,装完用 code --version 验证。

⚠️ macOS 上若 code 命令找不到,打开 VS Code,按 Cmd+Shift+P,输入「Shell Command」,选「Install 'code' command in PATH」。

Step 2 装必备扩展

在 VS Code 集成终端(`Ctrl+``)里一次性装上 AI 工作必备的扩展:

code --install-extension ms-python.python              # Python 语言支持、虚拟环境检测、运行/调试
code --install-extension ms-python.vscode-pylance      # 快速类型检查、自动补全、import 解析
code --install-extension ms-toolsai.jupyter            # 在 VS Code 里跑 Notebook、变量浏览器
code --install-extension eamodio.gitlens               # 看谁改了哪行、内联 git blame
code --install-extension ms-vscode-remote.remote-ssh   # 把远程 GPU 机器的目录当本地打开
code --install-extension ms-python.debugpy             # Python 逐行调试
code --install-extension ms-python.black-formatter     # 保存即格式化,风格一致
code --install-extension charliermarsh.ruff            # 快速 lint,抓常见错误
​

原课程 code/.vscode/extensions.json 含完整推荐列表,打开项目文件夹时 VS Code 会提示你安装。

Step 3 配置设置

把原课程 code/.vscode/settings.json 复制进你的配置,或通过「Settings → Open Settings (JSON)」手动加。AI 工作的关键设置:

{
    "python.analysis.typeCheckingMode": "basic",    // 保存前抓类型错(张量形状、API 参数)
    "editor.formatOnSave": true,                    // 不再操心格式,Black 全包了
    "editor.rulers": [88, 120],                     // Black 在 88 折行;120 提示注释太长
    "notebook.output.scrolling": true,              // 训练循环打印上千行,不滚动面板会爆
    "files.autoSave": "afterDelay"                  // 你会忘了保存,脚本会跑旧代码
}
​

为什么这几条重要:

• 类型检查开 basic:跑之前就抓出参数类型错,省下大量调试张量形状、API 参数的时间。
• 保存即格式化:再也不用想格式,Black 替你做。
• 标尺 88 与 120:Black 在 88 折行;120 提示文档与注释该精简了。
• Notebook 输出滚动:训练循环打印上千行,不开滚动输出面板会撑爆。
• 自动保存:你会忘了存,训练脚本会跑旧代码——自动保存堵住这个高频事故。

Step 4 终端集成

VS Code 的集成终端是你跑训练脚本、监控 GPU、管环境的地方。配置好默认 shell 与字体:

{
    "terminal.integrated.defaultProfile.osx": "zsh",
    "terminal.integrated.defaultProfile.linux": "bash",
    "terminal.integrated.fontSize": 13,
    "terminal.integrated.scrollback": 10000
}
​

分屏终端很有用:一个跑脚本,一个 nvidia-smi -l 1 监控 GPU。常用快捷键:切换终端 Ctrl+`,新建 Ctrl+Shift+`,分屏 macOS 用 Cmd+\、Linux/Windows 用 Ctrl+Shift+5。

Step 5 远程开发(SSH 进 GPU 机器)

这是 AI 工作最重要的扩展。你会把训练放在远程机器上(云端虚拟机、实验室服务器、Lambda、Vast.ai)。Remote-SSH 让你打开远程文件系统、编辑文件、跑终端、调试,一切如同本地。

设置步骤:

1. 装 Remote-SSH 扩展(Step 2 已装)。
2. 按 Ctrl+Shift+P,输入「Remote-SSH: Connect to Host」。
3. 输入 user@your-gpu-box-ip。
4. VS Code 会自动在远程机器上装好它的服务器组件。

设免密登录,先建 SSH 密钥并拷过去:

ssh-keygen -t ed25519 -C "your-email@example.com"
ssh-copy-id user@your-gpu-box-ip
​

再把主机写进 ~/.ssh/config 方便调用:

Host gpu-box
    HostName 203.0.113.50
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519
    ForwardAgent yes
​

之后「Remote-SSH: Connect to Host > gpu-box」一键直连。

💡 这套配置让你在本地编辑器里调远程 GPU 上的代码,体验与本地完全一致——文件树、终端、调试器、Notebook 全都指向远程。这是 AI 工程师远程协作的标准姿势。

三、框架对比:编辑器替代方案

Cursor

cursor.com 出的 VS Code 分支,内置 AI 代码生成。用同一套扩展生态与设置格式,本节所有配置都适用,直接导入同一份 settings.json 与 extensions.json 即可。

Windsurf

windsurf.com 的 AI 优先 VS Code 分支。同样:同扩展、同设置格式、同 Remote-SSH 支持。

Vim / Neovim

如果你已经在用 Vim/Neovim 且很顺手,就继续用。AI Python 工作的最小配置:pyright/pylsp(类型检查,经 Mason 或手动装)、nvim-lspconfig(语言服务器集成)、jupyter-vim 或 molten-nvim(类 Notebook 执行)、telescope.nvim(文件/符号搜索)、none-ls.nvim 配 black 与 ruff(格式化/lint)。

⚠️ 设计警示:如果你现在还没在用 Vim,别为了学 AI 顺手而去学它。Vim 的学习曲线会和你学 AI 工程抢注意力。先用 VS Code,等 AI 学扎实了再考虑迁移。

四、可复用产物

本节产出两个可复用文件(原课程 code/.vscode/):

• extensions.json:AI 工作的完整扩展推荐列表。打开项目文件夹时 VS Code 会提示一键安装。
• settings.json:AI 工作的关键设置模板(类型检查、保存即格式化、标尺、Notebook 滚动、自动保存、终端配置)。任何新项目复制即用。

五、练习

1. (Easy) 装 VS Code 与 Step 2 列出的所有扩展,把 settings.json 复制进配置;打开一个 Python 文件,确认 Pylance 显示类型提示、Black 保存即格式化。
2. (Medium) 配置好集成终端,开一个分屏:一个终端跑训练脚本(或任意长跑脚本),另一个 nvidia-smi -l 1(或 watch -n 1 nvidia-smi)监控 GPU;体感「编辑 + 监控」同框的高效。
3. (Hard) 如果你有远程机器(云虚拟机、实验室服务器都行),配好 SSH 密钥与 ~/.ssh/config,用 Remote-SSH 连上去打开一个文件夹,在远程跑一段 Python 与一个 Notebook,确认体验与本地无异;再试试在远程上设断点调试一段代码。

本节要点回顾

1. 编辑器是副驾驶:配好 20 分钟,每天省 20 分钟;配不好天天添堵。
2. AI 编辑器五要素:基础编辑器(VS Code)→ 扩展 → AI 专属设置 → 终端集成 → 远程开发,自底向上。
3. 八大必备扩展:Python、Pylance、Jupyter、GitLens、Remote-SSH、Debugpy、Black Formatter、Ruff。
4. 关键设置:类型检查 basic、保存即格式化、标尺 88/120、Notebook 输出滚动、自动保存。
5. 分屏终端:一个跑脚本,一个 nvidia-smi -l 1 监控 GPU。
6. Remote-SSH 是 AI 工作最重要扩展:把远程 GPU 机器当本地编辑调试,体验无缝。
7. SSH config + 密钥免密:一键直连远程机器。
8. 替代方案:Cursor/Windsurf 是 VS Code 超集,配置全适用;Neovim 适合已熟练的老手,新手别为它分心。

下一节,我们将进入「数据管理」——把模型权重、数据集、实验产物这些 AI 项目里的大块头组织好,让存储、版本与共享都有章法。