VS Code + Claude Code：远程开发与 Dev Container 工作流

VS Code 在本地编辑器市场份额第一不是因为它快（它不快），而是因为它的远程开发能力几乎吊打所有竞争对手。Remote SSH、Dev Containers、WSL2 这三套机制让你能在本地编辑、远程执行，环境隔离、团队一致。Claude Code 跟它们的组合方式有很多坑也有很多技巧，这篇专门讲清楚。前提：你已经装好了 VS Code 和 Claude Code CLI。

---

三种远程模式对比

VS Code 远程开发其实是三套独立技术，名字相近但行为差别很大：

	Remote SSH	Dev Containers	WSL
实际环境	远程 Linux 服务器	本地 / 远程容器	Windows 上的 Linux 子系统
启动方式	ssh + 安装 vscode-server	Docker + devcontainer.json	wsl.exe 启动发行版
文件位置	远端文件系统	容器内 + 卷挂载	WSL 文件系统 + Windows 挂载
团队一致性	看每台服务器配置	强（devcontainer.json 入 git）	各人 WSL 配置可能不同
启动速度	慢（首次装 server 几分钟）	中（拉镜像）	快（秒级）
适合	老牌服务器、GPU 机	团队、复杂依赖	Windows 个人开发
Claude Code 装哪	远端	容器内	WSL 内

下面分别讲。

---

Remote SSH + Claude Code：装哪边的取舍

VS Code 通过 SSH 连到远端服务器，本地只是个壳，所有计算、文件、终端都在远端。Claude Code 的装载位置有两种选择：

选项 1：装在远端（推荐）

# 连进 SSH 之后
ssh devuser@my-server
npm install -g @anthropic-ai/claude-code
# 配置 API key
mkdir -p ~/.claude
# 用 claude /login 走 OAuth，或者把 key 写进环境变量
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc

VS Code 的内置终端默认就是远端终端（你能看到提示符是远端的用户名@主机名），直接 claude 就是远端的 Claude。Claude 能读取/修改的也是远端文件，符合直觉。

选项 2：装在本地

如果你只想用 Claude 看代码而不想让它真的改远程文件，可以把 Claude 留在本地：

# 本地（Mac/Win/Linux）
claude --cwd /Users/me/mounted-from-remote

但是这要求你把远端代码 mount 到本地（用 sshfs 或者 mutagen），意义不大。绝大多数情况选项 1 更合理。

注意事项：

• 远端的 Node.js 版本要够新（18+）才能跑 Claude Code
• 远端如果是 Air Gap 内网，要解决出网到 api.anthropic.com 的代理问题：

# 通过 SSH 反向代理走本地出网
ssh -R 8888:127.0.0.1:8888 devuser@server
# 远端 ~/.claude/config.json
{
  "proxy": "http://127.0.0.1:8888"
}

• VS Code 的 settings.json 在远端的 ~/.vscode-server/data/Machine/settings.json，团队共享 Claude 设置时记得同步这个

---

Dev Containers：把 Claude Code 内置到团队配置

Dev Containers 是终极武器：一份 devcontainer.json 入 git，新人 clone 后按 F1 选 “Reopen in Container”，三分钟拿到一个跟全队一模一样的开发环境，Claude Code 也跟着一起进来。

最小可用 devcontainer.json：

{
  "name": "myapp-dev",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code && npm install",
  "containerEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached"
  ]
}

几个关键点：

1. postCreateCommand 安装 Claude Code，新人不需要手动装
2. containerEnv 把本地的 API key 注入容器，不要把 key 写死在文件里
3. mounts 把宿主机 ~/.claude 挂到容器内，复用 OAuth 凭证和会话历史
4. extensions 里加上 Anthropic 官方扩展，容器启动时自动装

新人加入项目流程变成：

git clone team/myapp
cd myapp
code .          # VS Code 打开
# 弹窗：在容器内重新打开
# 点 "Reopen in Container"
# 等 2 分钟
# 终端里直接 claude，开干

---

Dev Container 模板：Node / Python / Go 三语言

实战会用到的三个完整模板，可以直接抄。

Node.js + TypeScript

{
  "name": "node-ts-app",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code typescript ts-node && npm install",
  "containerEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
    "NODE_ENV": "development"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "orta.vscode-jest"
      ]
    }
  },
  "forwardPorts": [3000, 9229],
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind"
  ],
  "remoteUser": "node"
}

Python + Poetry

{
  "name": "python-app",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "features": {
    "ghcr.io/devcontainers-extra/features/poetry:2": {}
  },
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code && poetry install --no-root",
  "containerEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
    "PYTHONUNBUFFERED": "1"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "ms-python.python",
        "ms-python.vscode-pylance",
        "charliermarsh.ruff"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python",
        "python.testing.pytestEnabled": true
      }
    }
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/root/.claude,type=bind"
  ]
}

注意 Python 容器默认 root，所以 .claude 挂到 /root/.claude。Node 容器默认 node 用户，挂到 /home/node/.claude。这种小差别经常出问题，要仔细。

Go

{
  "name": "go-app",
  "image": "mcr.microsoft.com/devcontainers/go:1.22",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    }
  },
  "postCreateCommand": "npm install -g @anthropic-ai/claude-code && go mod download",
  "containerEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
    "GOFLAGS": "-mod=mod"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "golang.go"
      ],
      "settings": {
        "go.useLanguageServer": true,
        "go.lintTool": "golangci-lint"
      }
    }
  },
  "mounts": [
    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind"
  ]
}

Go 基础镜像里没有 Node，所以要通过 features 装 Node 才能再装 Claude Code（Claude Code 是 npm 包）。这是 Go 项目最容易卡住的地方。

---

WSL2 + Claude Code on Windows：踩坑指南

Windows 用户用 WSL2 是几乎唯一靠谱的 Claude Code 体验路径。但坑很多。

坑 1：npm 全局路径

在 WSL Ubuntu 里默认用 sudo npm install -g 会把 Claude 装到 /usr/lib/node_modules/，导致每次升级要 sudo。推荐改成用户目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code   # 不用 sudo 了

坑 2：VS Code 终端跑的是 Windows shell

打开 VS Code 后默认终端是 PowerShell。要让它跑在 WSL：

// settings.json
{
  "terminal.integrated.defaultProfile.windows": "Ubuntu (WSL)",
  "terminal.integrated.profiles.windows": {
    "Ubuntu (WSL)": {
      "path": "C:\\Windows\\System32\\wsl.exe",
      "args": ["-d", "Ubuntu"]
    }
  }
}

或者更彻底——用 Remote-WSL 扩展，让整个 VS Code 实例都在 WSL 上下文里跑。状态栏左下角会显示 WSL: Ubuntu。

坑 3：文件权限和路径

把项目放在 C:\Users\...\Documents\projects\myapp 然后在 WSL 里访问 /mnt/c/Users/.../projects/myapp——Claude Code 能用，但 IO 速度比 Linux 原生慢 5-10 倍，npm install 慢得像狗。

正确做法：项目放 WSL 文件系统

# WSL 终端
mkdir -p ~/projects
cd ~/projects
git clone git@github.com:team/myapp
cd myapp
code .   # 这会自动用 Remote-WSL 模式打开 VS Code

VS Code 通过 \\wsl$\Ubuntu\home\me\projects\myapp 访问文件，但走的是 9P 协议优化路径，速度接近原生。

坑 4：环境变量传递

Windows 下设的 ANTHROPIC_API_KEY 默认不会传到 WSL。要么在 ~/.bashrc 里再 export 一次，要么用 WSLENV：

# Windows PowerShell
[Environment]::SetEnvironmentVariable("WSLENV", "ANTHROPIC_API_KEY/u", "User")

/u 表示传给 WSL 的 Unix 进程。

---

Multi-root Workspace：Claude 怎么处理多项目根

VS Code 的 multi-root workspace 允许一个窗口同时打开多个不相干的项目目录。Claude Code 一次只认一个 cwd，跑在哪个项目里只看你启动时在哪里。

.code-workspace 文件示例：

{
  "folders": [
    { "path": "../frontend" },
    { "path": "../backend" },
    { "path": "../shared-types" }
  ],
  "settings": {
    "terminal.integrated.cwd": "${workspaceFolder:frontend}"
  }
}

实战技巧：

1. 给每个子项目开独立的内置终端，每个终端的 cwd 设到对应项目
2. 终端面板右上角下拉可以重命名：claude-frontend、claude-backend、claude-shared
3. 每个终端跑各自的 claude，互不干扰
4. 跨项目的问题，给 Claude 完整路径：检查 ../backend/src/api/user.ts 的接口，更新 ./src/api/types.ts

或者用一招——在父目录起 Claude，让它看全景：

cd ~/projects/myapp-monorepo  # 父目录包含 frontend/、backend/、shared/
claude
> 同时改 frontend 和 backend 让它们共用 shared/types/user.ts 的 User 类型

Claude 一次能看到三个项目所有文件，能改跨项目的协同问题。代价是上下文消耗更大、Token 更贵。

---

VS Code Live Share + Claude Code 的局限

Live Share 看着像 Zed Channel，但实际差很多：

能力	Live Share	Zed Channel
共享终端	是（但 host 关 = 关）	是（持久）
Claude Code 实时同步给 Guest	不	是
协作不需要 Host 在线	不能	能

具体来说：Host 在 Live Share 终端里跑 claude，Guest 看到的只是终端输出，看不到 Claude 修改文件的实时进度。Guest 想看 diff 得自己 git diff。如果 Host 退出 session，所有共享立刻断开。

如果团队真的需要协作 + Claude Code，Zed Channel 体验更好。VS Code Live Share 更适合：

• 一次性的 mob debugging
• 远程面试看候选人写代码
• Quick pair on a single function

长期协作还是 PR review + Dev Container 更稳。

---

团队配置共享：.vscode + CLAUDE.md 入 git

一个项目应该有这些东西入 git，新人 clone 后零配置即可工作：

myapp/
├── .vscode/
│   ├── settings.json         # 编辑器设置
│   ├── extensions.json       # 推荐扩展
│   └── launch.json           # 调试配置
├── .devcontainer/
│   └── devcontainer.json     # 容器化开发环境
├── .claude/                  # Claude Code 配置（部分入 git）
│   ├── commands/             # 自定义 slash command
│   │   └── deploy.md
│   └── hooks/                # Pre/Post 钩子
├── CLAUDE.md                 # 项目级 Claude 指导
└── .gitignore

.vscode/settings.json 示例：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "files.eol": "\n",
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true
  },
  "claudeCode.allowedCommands": ["npm test", "npm run build"]
}

.vscode/extensions.json：

{
  "recommendations": [
    "anthropic.claude-code",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-azuretools.vscode-docker"
  ]
}

CLAUDE.md 示例：

# myapp 项目

技术栈：Next.js 15、PostgreSQL、Stripe、Vercel

## 规则
- 用 pnpm 不用 npm
- API route 必须有 zod schema 验证
- DB 改动必须配 migration
- 提交前跑 `pnpm test` 和 `pnpm typecheck`

## 重要文件
- `src/lib/auth.ts`：自定义 session 管理，不要替换成 NextAuth
- `prisma/schema.prisma`：Schema 修改后立即 `pnpm prisma migrate dev`

## 不要做
- 不要引入新的全局状态管理库（Redux/Zustand），用 React Context
- 不要直接调 Stripe SDK，全部走 `src/lib/billing/` 包装

.gitignore 排除 secret：

.claude/credentials
.claude/session*
.env
.env.local

这套配置入 git 之后，新人三步走：

git clone team/myapp
cd myapp
code .                              # VS Code 提示装推荐扩展
# Reopen in Container 弹窗，点是
# 进入容器，devcontainer.json 自动装 Claude Code
# 终端里 claude，自动读 CLAUDE.md，立刻能干活

这是 VS Code + Claude Code 在团队场景下最大的杠杆——所有人共享一份完全相同的开发环境，包括 AI 助手的项目指导。

---

相关阅读

• 安装配置：VS Code 中安装与配置 Claude Code

其他编辑器工作流：

• Cursor + Claude Code：日常开发完整工作流
• WebStorm + Claude Code：JS/TS 项目实战工作流
• Vim + Claude Code：纯键盘终端工作流
• Neovim + Claude Code：Lua 生态深度集成
• Zed Channel 多人协作开发：搭配 Claude Code 实战

相关编辑器安装教程：

• Cursor 中安装与配置 Claude Code
• WebStorm / IntelliJ 中安装与配置 Claude Code
• Vim / Neovim 中安装与配置 Claude Code
• Zed 中安装与配置 Claude Code