VS Code 联动 Claude Code 安装教程实践整理
作者：袖梨
2026-08-20
平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“VS Code 联动 Claude Code 安装教程”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际使用顺序，把思路、关键写法和容易踩坑的地方讲清楚，方便你直接对照操作。
适用系统：Ubuntu
1. 前置准备
1.1 系统要求
- 操作系统：Ubuntu 20.04 或更高版本
- Node.js：18.x 或更高版本
- npm：9.x 或更高版本
1.2 检查环境版本
node --version npm --version
版本过低？ 采用 nvm 安装最新版本：
# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 重新加载 shell source ~/.bashrc # 安装最新 LTS 版本 nvm install --lts
1.3 新建工作目录
重要：目录名采用连字符（-），避免空格
mkdir -p ~/claude-code cd ~/claude-code
2. 安装 Claude Code CLI
2.1 全局安装
npm install -g @anthropic-ai/claude-code
2.2 验证安装
claude --version
显示版本号即为安装成功
3. 安装 code-server
3.1 下载并安装
# 下载最新版本 wget https://github.com/coder/code-server/releases/download/v4.23.1/code-server-4.23.1-amd64.deb # 安装 sudo dpkg -i code-server-4.23.1-amd64.deb # 如果缺少依赖 sudo apt-get install -f
3.2 设置 code-server
# 创建配置目录 mkdir -p ~/.config/code-server # 生成配置文件 cat > ~/.config/code-server/config.yaml <<EOF bind-addr: 127.0.0.1:8080 auth: password password: 你的密码 cert: false EOF
3.3 启动服务
方式一：手动启动
code-server --config ~/.config/code-server/config.yaml
方式二：系统服务（建议）
sudo systemctl enable code-server@$USER sudo systemctl start code-server@$USER
3.4 访问 Web 界面
浏览器打开：（链接已移除）
输入你设置的密码即可采用
4. 设置 Claude Code
4.1 交互式设置
claude configure
按提示完成设置：
- 界面语言（建议中文）
- Coding 套餐
- API 密钥
- 编码工具
4.2 手动设置（高级）
设置文件位置：~/.claude/settings.json
采用第三方提供商示例：
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "你的认证令牌",
"API_TIMEOUT_MS": "3000000"
},
"enabledPlugins": {
"你的插件名": true
},
"language": "chinese"
}4.3 验证设置
claude
提示：如果能正常响应对话，说明设置成功
5. 安装 Claude Code VS Code 扩展
5.1 借助扩展市场安装
- 打开 code-server Web 界面
- 点击左侧 扩展图标（方块）
- 搜索 "Claude Code"
- 选择 Anthropic 发布的扩展
- 点击 安装
5.2 设置扩展
重要：采用第三方提供商需跳过登录
方法一：借助设置界面
- 打开设置（Ctrl+,）
- 搜索 Claude Code login
- 勾选 Disable Login Prompt
方法二：手动编辑
编辑 ~/.local/share/code-server/User/settings.json：
{
"claudeCode.disableLoginPrompt": true
}5.3 打开 Claude Code 面板
方式一：Spark 图标
- 点击编辑器右上角的 图标
方式二：命令面板
- 按
Ctrl+Shift+P - 输入 "Claude Code"
- 选择打开方式
方式三：状态栏
- 点击右下角的 " Claude Code"
5.4 测试连接
在面板中发送测试消息，正常回复即表示成功
6. 常用问题及解决方案
问题 1：Failed to spawn Claude Code process
症状
Error: spawn /path/to/claude code EACCES
原因
- 路径中包含空格
- 设置文件路径错误
- CLI 未正确安装
解决方案
# 步骤 1：检查 VS Code 设置
cat ~/.local/share/code-server/User/settings.json
# 步骤 2：搜索错误路径
grep -r "claude code" ~/.local/share/code-server/User/
# 步骤 3：批量修复
find ~/.local/share/code-server/User/History/ -name "*.json"
-exec sed -i '/"claudeCode.claudeProcessWrapper"/d' {} ;
# 步骤 4：验证 CLI 安装
which claude
claude --version
# 步骤 5：重启服务
sudo systemctl restart code-server@$USER
# 步骤 6：刷新浏览器（Ctrl+F5）问题 2：登录界面卡住
症状
显示登录选项（Google/GitHub/Email）但无法登录
解决方案
编辑 ~/.local/share/code-server/User/settings.json：
{
"claudeCode.disableLoginPrompt": true
}重启 code-server 并刷新浏览器
问题 3：终端无法连接 IDE
症状
执行 /ide 命令时提示找不到可用的 IDE
解决方案
# 1. 确认 code-server 正在运行 # 2. 切换到正确的项目目录 cd ~/claude-code/项目1 # 3. 启动 Claude Code claude # 4. 连接 IDE /ide
确保终端目录与 IDE 打开的项目目录一致
问题 4：扩展安装后无响应
解决方案
# 检查版本 code-server --version # 需要 1.98.0+ claude --version # 查看日志 # Ctrl+Shift+P → "Show Logs" → "Extension Host" # 重载窗口 # Ctrl+Shift+P → "Developer: Reload Window"
问题 5：环境变量不生效
解决方案
# 检查配置文件 cat ~/.claude/settings.json # 验证 JSON 格式 cat ~/.claude/settings.json | jq . # 检查项目级配置 cat ~/your-project/.claude/settings.local.json
问题 6：权限错误 (EACCES)
解决方案
# 检查可执行文件权限 ls -la $(which claude) # 添加执行权限 chmod +x $(which claude) # 修复 npm 全局目录权限 sudo chown -R $USER:$(id -gn $USER) ~/.npm-global
最佳实践
命名规范
采用连字符命名目录，避免空格
- ~/claude-code
- ~/claude code
设置管理
重置设置时可安全删除：
- ~/.claude/settings.json
- ~/.local/share/code-server/User/
版本控制
将设置文件加入版本控制便于同步
保持更新
# 更新 CLI npm update -g @anthropic-ai/claude-code # 更新 code-server sudo apt-get update && sudo apt-get upgrade code-server
技术兼容
- Claude Code 文档：（链接已移除）
- code-server 文档：（链接已移除）
- 问题反馈：（链接已移除）
结合项目来看，总的来说，VSCode这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。
