平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“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 借助扩展市场安装

1. 打开 code-server Web 界面
2. 点击左侧 扩展图标（方块）
3. 搜索 "Claude Code"
4. 选择 Anthropic 发布的扩展
5. 点击 安装

5.2 设置扩展

重要：采用第三方提供商需跳过登录

方法一：借助设置界面

1. 打开设置（Ctrl+,）
2. 搜索 Claude Code login
3. 勾选 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这部分内容适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。