VS Code 配置 Claude Code 完整教程：环境安装、settings.json 与 API 接入

1. 为什么要在 VS Code 里跑 Claude Code

1.1 这个组合到底解决了什么问题

先说清楚一件事：Claude Code 本身是一个跑在终端里的命令行工具，它不是一个 VS Code 插件。很多人第一次听到“VS Code 配置 Claude Code”会误以为要去扩展市场搜一个插件装上，其实不是这么回事。它的本质是：你在 VS Code 的集成终端里调用 Claude Code 这个 CLI 工具，让它读取你当前项目的文件、理解上下文、帮你改代码、跑命令、做重构。

那为什么不直接在系统终端里用，非要放进 VS Code？我自己的体会是三个字：上下文。VS Code 的集成终端天然带着当前工作区的路径信息，你打开哪个项目文件夹，终端就在哪个目录下启动，Claude Code 一进去就能看到整个项目的结构。另外 VS Code 的终端支持多标签、支持输出高亮、支持快捷键唤起，配合 Claude Code 的交互式对话，整个体验比在独立终端窗口里切来切去顺畅得多。

这个教程适合谁？适合已经装了 VS Code、平时用 Node.js 或者前端/全栈开发、想尝鲜 AI 辅助编程但又被各种环境问题卡住的人。也适合那些之前只在网页版聊天窗口里贴代码、觉得“复制粘贴太累”的开发者。你不需要是命令行高手，但至少要能看懂cd、npm这类基础命令。

1.2 先搞明白 Claude Code 的工作方式

Claude Code 的运行逻辑跟普通的代码补全插件完全不同。像 Copilot 那种是在你打字的时候给你补全下一行，而 Claude Code 是对话式的：你用自然语言描述需求，它自己去读文件、分析、然后给出修改方案，甚至直接帮你执行。它背后依赖的是 API 调用，也就是说你需要有一个可用的 API 端点和对应的密钥。

这里有个关键点很多人会踩坑：Claude Code 默认走的是官方的 API 服务，但在实际使用中，不少开发者会配置成兼容的第三方 API 端点（比如各种兼容接口的模型服务）。这就涉及到settings.json里的环境变量配置，也是后面要重点讲的部分。你要理解的是，Claude Code 本身只是个“客户端外壳”，真正干活的是它调用的那个模型 API。所以配置的核心就两件事：让 CLI 能跑起来，以及让它知道去哪里调用 API。

提示：不要把 Claude Code 和 VS Code 扩展市场里的 AI 插件混为一谈。它是独立的 CLI 工具，VS Code 只是给它提供了一个舒适的运行环境。

2. 环境准备：Node.js 与 VS Code 的前置检查

2.1 Node.js 版本要求与安装验证

Claude Code 是基于 Node.js 开发的 CLI 工具，所以第一步是确保你的机器上有合适版本的 Node.js。根据我的实测，Node.js 18 及以上版本是比较稳妥的选择，推荐直接用 LTS 版本（比如 20.x 或 22.x）。版本太低会在安装阶段就报错，提示引擎不兼容。

安装 Node.js 有几种方式，Windows 用户直接去官网下载安装包最省事，macOS 用户可以用 Homebrew，Linux 用户看发行版用对应的包管理器。装完之后一定要验证，打开终端执行：

node -v npm -v

两条命令都要能正常输出版本号。如果node -v有输出但npm -v报错，说明 npm 没跟着装好，这种情况在 Windows 上偶尔出现，重新跑一遍安装包选“修复”通常能解决。

我踩过的一个坑是：机器上装了多个 Node 版本（比如之前装过 nvm 又手动装了一个），导致node -v和实际被调用的路径不一致。验证的时候顺手跑一下which node（macOS/Linux）或where node（Windows），确认你看到的版本就是实际生效的那个。版本管理工具用 nvm 的话，记得nvm use切到正确版本再装 Claude Code。

2.2 VS Code 安装与中文环境配置

VS Code 的安装没什么好说的，官网下载对应平台版本，一路下一步。但有两个细节值得提。第一，Windows 安装时建议勾选“添加到 PATH”和“将‘通过 Code 打开’操作添加到右键菜单”，这样后面在项目目录里直接右键就能打开，省得每次手动找文件夹。第二，如果你习惯中文界面，装完之后去扩展市场搜“Chinese”装官方中文语言包，重启即可生效。

VS Code 装好后，重点确认一件事：集成终端能不能正常工作。按Ctrl+`（反引号）唤起终端，看看默认的 shell 是什么。Windows 上默认可能是 PowerShell，macOS/Linux 一般是 bash 或 zsh。这个 shell 环境很重要，因为 Claude Code 就在这里面跑，如果 shell 本身有问题（比如 PowerShell 执行策略限制），CLI 也会跟着出问题。

注意：如果你在 Windows 上用 PowerShell 遇到脚本执行被阻止的报错，可以临时用Set-ExecutionPolicy -Scope CurrentUser RemoteSigned放开当前用户的策略。改之前先确认公司或团队有没有相关安全规定。

2.3 网络与 API 可用性预判

在正式装 Claude Code 之前，我建议先做一次“连通性预判”。因为 Claude Code 要调用 API，如果你的网络环境访问不了对应的 API 端点，装完了也是白装，会在登录或首次请求时报连接错误。

判断方法很简单：确认你手头有没有可用的 API 密钥，以及对应的 API 端点地址。如果你用的是官方服务，确认账号状态正常；如果你用的是兼容的第三方端点，提前把 base URL 和 key 准备好。这一步看起来是废话，但我见过太多人装完 CLI 才发现自己根本没有可用的 key，然后卡在登录环节反复折腾。

把这三样东西提前记在一个文本文件里：API Key、Base URL（如果需要自定义）、你要用的模型名称。后面配置settings.json的时候直接复制，避免手打出错。

3. 安装 Claude Code CLI 的完整流程

3.1 全局安装命令与常见报错处理

环境确认无误后，安装本身其实就一行命令：

npm install -g @anthropic-ai/claude-code

-g表示全局安装，这样在任何目录下都能直接调用claude命令。安装过程会拉取依赖包，网速正常的话一两分钟搞定。

但这一步是报错重灾区，我整理了几个高频问题。第一个是权限错误，在 macOS/Linux 上如果没加 sudo 会提示EACCES，这时候不要无脑加 sudo，更好的做法是配置 npm 的全局目录到用户目录下，避免污染系统权限。第二个是网络超时，npm 默认源在国内访问可能很慢，可以临时切换到国内镜像源加速，装完再切回来。第三个是版本冲突，如果之前装过旧版本，先npm uninstall -g @anthropic-ai/claude-code卸干净再装。

安装完成后验证：

claude --version

能输出版本号就说明 CLI 装好了。如果提示command not found，八成是 npm 全局 bin 目录没加到 PATH 里。跑npm config get prefix看看全局目录在哪，然后把这个目录下的 bin 子目录加到系统 PATH 中。

3.2 首次启动与登录方式选择

装好之后，在任意目录下敲claude就能启动。首次启动它会引导你完成认证。这里有两种常见路径：一种是通过官方账号授权登录，另一种是配置 API Key 直接使用。

如果你走 API Key 这条路，通常需要设置环境变量或者在配置文件里写明。启动后如果看到类似login failed或者check api token的提示，基本就是认证信息没配对。我的建议是：先把认证跑通，再进项目。找一个空目录启动 Claude Code，确认它能正常响应，再去实际项目里用，这样能把环境问题和项目问题分开排查。

提示：首次启动时如果卡在某个界面不动，先按Ctrl+C退出，检查网络和认证配置，不要干等着。

3.3 把 Claude Code 接进 VS Code 终端

CLI 装好、认证跑通之后，接入 VS Code 就水到渠成了。打开你的项目文件夹，按Ctrl+`唤起集成终端，直接输入claude回车。如果一切正常，你会看到 Claude Code 的交互界面在终端里启动，并且它已经能感知到当前项目的文件结构。

这里有个体验优化点：VS Code 的终端默认可能开在项目根目录，但如果你有 monorepo 或者多包结构，可能需要先cd到具体子目录再启动。另外，建议给终端设置一个顺手的快捷键，或者用 VS Code 的“终端配置文件”功能，把启动 Claude Code 做成一个一键操作。具体做法是在settings.json里配置终端 profile，这个后面讲配置文件时一起说。

实测下来，把 Claude Code 放在 VS Code 终端里跑，最大的好处是边看代码边对话。它改完文件，你直接在编辑器里就能看到 diff，不用切窗口。这种流畅感是独立终端给不了的。

4. settings.json 配置文件深度拆解

4.1 配置文件的位置与优先级

settings.json是 Claude Code 的核心配置文件，很多行为都靠它控制。它的位置分几个层级，优先级从高到低大致是：项目级配置（项目根目录下的.claude/settings.json或类似路径）、用户级配置（用户主目录下的配置文件夹）。项目级配置会覆盖用户级配置，这个设计很合理——团队可以统一项目规范，个人又能保留自己的偏好。

找配置文件的时候，如果你不确定它到底读的是哪个，可以在 Claude Code 里用相关命令查看当前生效的配置路径。我一般习惯把通用配置放在用户级，把项目特有的（比如特定的模型、特定的权限）放在项目级。这样换项目的时候不用重复配。

需要特别说明的是，网上有些资料会把 VS Code 自己的settings.json和 Claude Code 的settings.json搞混。这是两个完全不同的文件：VS Code 的那个在.vscode/settings.json或者用户设置里，管的是编辑器行为；Claude Code 的那个管的是 CLI 行为。别改错了地方。

4.2 环境变量与 API 端点配置

配置文件里最关键的几项，就是跟 API 调用相关的环境变量。典型的需要配置的项包括 API 密钥、API 基础地址（base URL）、以及默认使用的模型名称。格式上一般是在配置里写一个env字段，里面放键值对。

举个结构示例（具体字段名以你所用版本的实际文档为准）：

{ "env": { "ANTHROPIC_API_KEY": "你的密钥", "ANTHROPIC_BASE_URL": "你的端点地址", "ANTHROPIC_MODEL": "你要用的模型名" } }

这里有个大坑：模型名称必须和端点实际支持的名称完全一致。我见过有人报api error: 400 the supported api model names are ...这种错，原因就是配置里写的模型名跟服务端支持的对不上。比如服务端只支持某几个特定名称的模型，你写了个别的，请求直接被拒。解决办法就是去确认你的 API 服务到底支持哪些模型名，然后一字不差地填进去。

另一个高频错误是maximum context length超限，提示你输入的 token 数超过了模型上限。这不是配置错误，而是你一次喂给它的内容太多了。处理方式是缩小提问范围，或者让它先读关键文件而不是整个项目。

4.3 权限与安全相关设置

Claude Code 能读文件、能执行命令，所以权限控制很重要。配置文件里通常可以设置哪些操作需要确认、哪些目录允许访问、哪些命令禁止执行。我的建议是：初期把确认级别调高，让它每次要改文件或跑命令时都问你一下，等你摸清它的行为模式了，再逐步放开一些低风险操作。

特别是涉及删除文件、执行 shell 命令这类操作，一定要保留人工确认。我自己的配置里，读取类操作放开，写入和删除类操作必须确认。这样既享受了效率，又不至于某天醒来发现项目被改得面目全非。

注意：不要把 API 密钥明文提交到 Git 仓库。项目级的配置文件如果包含密钥，记得加到.gitignore里，或者用环境变量注入的方式，别硬编码。

5. 实操：从零到能用的完整走查

5.1 一次完整的配置流程记录

我把整个流程按顺序走一遍，你可以对照着操作。第一步，确认 Node 版本node -v输出 18 以上。第二步，全局安装 CLInpm install -g @anthropic-ai/claude-code。第三步，claude --version验证安装。第四步，在空目录启动claude完成认证。第五步，找到配置文件位置，写入 API 相关配置。第六步，重启 Claude Code 让配置生效。第七步，进 VS Code 打开项目，终端里启动claude，测试一个简单请求，比如“列出当前项目的目录结构”。

每一步都要验证通过再进下一步，不要跳步。我见过有人一口气全配完然后报错，结果根本不知道是哪一步出的问题，只能全部推倒重来。分步验证虽然慢一点，但排查成本低得多。

5.2 验证配置是否生效的方法

配置写完不代表生效，一定要验证。最简单的验证方式是启动 Claude Code 后问它一个需要调用 API 的问题，比如“帮我总结一下当前目录下有哪些文件”。如果它能正常回答，说明 API 通了。如果报错，看错误信息里的关键词：401一般是密钥问题，400多半是模型名或请求格式问题，连接超时则是网络或端点地址问题。

还有一个验证技巧：在 Claude Code 里查看当前生效的配置。很多版本支持类似/config或/status的命令，能直接显示当前用的模型、端点、认证状态。这比猜要靠谱得多。如果显示的信息和你配置文件里写的不一致，说明配置没被正确加载，检查文件路径和格式。

5.3 在真实项目中的第一次使用

配置跑通后，第一次在真实项目里用，建议从只读任务开始。比如让它分析代码结构、解释某个模块的作用、找出潜在的 bug。这些任务不改文件，风险低，还能帮你判断它对你项目的理解程度。

等你对它的输出质量有信心了，再尝试让它改代码。改的时候一定要用版本控制（Git），改完先看 diff 再决定要不要保留。我自己的习惯是：让 Claude Code 改完，先在 VS Code 的源代码管理面板里过一遍改动，确认没问题再提交。这样即使它改错了，一个git checkout就能回滚。

6. 常见报错与排查速查

6.1 API 相关错误对照表

这张表基本覆盖了八成以上的报错。遇到问题先对号入座，能省不少时间。

6.2 安装与运行环境问题

安装阶段的报错，前面提过权限和网络两类。运行阶段的问题，常见的是command not found（PATH 没配好）和版本不兼容（Node 太旧）。还有一种情况是 VS Code 终端里的环境和系统终端不一致，比如 VS Code 用的是某个虚拟环境的 shell，导致claude命令找不到。解决办法是在 VS Code 里检查终端默认 shell 设置，确保和系统一致。

另外，如果你在 VS Code 里遇到终端启动慢或者卡住，可能是 shell 的启动脚本里有耗时操作。可以试试把 VS Code 终端配置成不加载完整 profile 的模式，启动会快很多。

6.3 我踩过的几个真实坑

第一个坑：配置文件写好了但没生效，折腾半天发现是文件放错了目录。Claude Code 读的是它自己的配置路径，不是 VS Code 的。第二个坑：模型名大小写或者连字符写错，报 400 错误，对着文档一个字一个字核对才发现问题。第三个坑：在项目里让它改代码，没先提交 Git，结果改乱了想回滚都难，从那以后我养成了“先 commit 再让它动手”的习惯。

这些坑的共同点是：都能通过分步验证和版本控制避免。配置分步测，改代码前先存档，这两条做到了，基本不会出大问题。

7. 让 Claude Code 更好用的几个配置技巧

7.1 终端 profile 与快捷键优化

在 VS Code 的settings.json里可以配置终端 profile，把启动 Claude Code 做成一个预设。这样你按快捷键新建终端时，直接就是 Claude Code 的界面，省去每次手敲claude的麻烦。配置方式是在终端 profile 里加一个自定义项，命令指向claude，然后把它设为默认或者绑定快捷键。

快捷键方面，VS Code 支持自定义键绑定。我给“新建 Claude Code 终端”设了一个顺手的组合键，用起来跟唤起普通终端一样快。这种小优化看着不起眼，但每天用几十次，累积下来省的时间很可观。

7.2 项目级配置的团队协作价值

如果你在团队里推广 Claude Code，项目级配置文件就很有价值了。把统一的模型、端点、权限策略写进项目配置，提交到仓库，团队成员拉下来就能用一致的设置。这样避免了“你配你的、我配我的”导致的混乱，也方便统一管理密钥的注入方式（比如通过 CI 的环境变量，而不是硬编码）。

不过要注意，项目级配置里不要放个人密钥。密钥应该通过环境变量或者本地的用户级配置注入，项目配置只放那些可以公开的、团队共享的设置。

7.3 与其他 AI 工具的配合思路

Claude Code 不是孤立的，它可以和 VS Code 里的其他 AI 工具配合。比如用某个插件做行内补全，用 Claude Code 做跨文件的重构和对话式开发，两者分工不同，互不冲突。我自己的用法是：日常敲代码靠补全插件提效，遇到需要理解整个模块、做较大改动的时候，切到 Claude Code 对话。

这种组合的关键是别让它们同时改同一个文件，否则容易冲突。我的习惯是同一时间只让一个工具动代码，另一个只做只读分析。这样职责清晰，也不会出现改动互相覆盖的情况。

8. 关于模型选择与 API 调用的一点经验

8.1 不同模型在代码任务上的表现差异

Claude Code 支持配置不同的模型，而不同模型在代码任务上的表现确实有差异。一般来说，参数规模更大的模型在复杂重构、跨文件理解上更强，但响应更慢、成本更高；轻量模型响应快、成本低，适合简单的问答和单文件修改。我的建议是：日常小任务用轻量模型，复杂任务切大模型，按需切换，别一刀切。

配置多个模型的方式是在配置文件里预设几套，或者用命令行参数临时指定。具体怎么切，看你用的 CLI 版本支持哪种方式。关键是心里要有一杆秤：这个任务值不值得用更贵的模型。

8.2 API 调用量与成本控制

API 是按调用量计费的，用起来爽，账单也可能吓人。控制成本有几个实用手段：一是控制上下文长度，别动不动就让它读整个项目，指定关键文件即可；二是善用缓存，很多 API 服务对重复的上下文有缓存优惠；三是设置用量提醒，很多平台支持配置预算告警，超了会通知你。

我自己的做法是每周看一眼用量趋势，如果某天突然飙升，回头查查是不是哪个任务喂了太多内容。这种复盘能帮你找到浪费点，长期下来省不少。

8.3 端点兼容性与模型名匹配

最后再强调一次模型名匹配的问题。如果你用的是兼容端点，服务端支持的模型名可能和官方不一样。配置前一定要拿到服务端的模型列表，照着填。报400错误的时候，第一反应就是去核对模型名，而不是怀疑网络或密钥。这个坑我踩过不止一次，每次都是名字对不上。

另外，有些端点对请求格式有额外要求，比如特定的 header 或者参数。如果基础配置都对但还是报错，去看看端点提供方的文档，确认有没有特殊要求。兼容性这东西，细节决定成败。

说到底，在 VS Code 里配 Claude Code，难点从来不是那几行命令，而是把环境、认证、配置这三块理顺。理顺之后，它就是一个随叫随到的结对编程伙伴。我现在的工作流里，它已经成了打开项目后的第一个动作——先让它扫一遍代码，问问今天的任务从哪下手，比我自己瞎翻文件快多了。