上周有个读者问我："三木，我装了 Claude Code，但不知道为什么它就是不工作。" 我让他截图，发现他连 API Key 都没配置，就开始疯狂问 Claude "帮我写个登录页面"。这不是个例——我在社群里看到至少 30% 的人卡在安装这一步，要么环境没配对，要么装完了不知道怎么验证，最后骂一句"AI 编程都是噱头"就卸载了。

为什么这个指南值得存在

市面上关于 Claude Code 的教程要么是官方文档的机翻版本（看完还是不知道怎么开始），要么是 UP 主录的 20 分钟视频（你得暂停 50 次才能跟上）。

我自己第一次装 Claude Code 的时候也踩了坑：VS Code 版本太低导致插件装不上，API 配额用完了还以为是网络问题，写完第一个 Prompt 发现 Claude 给我生成了一堆 TypeScript 但我项目是纯 JavaScript……这些坑都很蠢，但每个都能让你卡半小时。

这篇文章要解决的问题很简单：让你在 30 分钟内完成安装、配置、验证，并真正跑通第一个 AI 辅助开发的完整流程。不是装完就结束，而是确保你能用它写出第一行有用的代码。

第一步：确认你的开发环境（90%的人跳过这步然后翻车）

在装 Claude Code 之前，先检查这三件事：

1. VS Code 版本 ≥ 1.85

打开 VS Code，按 Cmd/Ctrl + Shift + P，输入 About，看版本号。如果低于 1.85，先去官网更新。

为什么这个版本号重要？ 因为 Claude Code 依赖 VS Code 的 Language Server Protocol 新特性，老版本会导致代码补全功能失效。我见过有人用 1.78 的版本装插件，表面上能用，但 Claude 的上下文理解能力直接废掉一半。

2. Node.js 版本 ≥ 18

终端运行：

node -v

如果低于 18 或者直接报错"command not found"，去 nodejs.org 装 LTS 版本。

说人话就是： Claude Code 在处理项目依赖分析时会调用 Node 环境，没有它你只能写单文件脚本，涉及 npm 包的项目就抓瞎。

3. 网络能访问 api.anthropic.com

终端运行：

curl -I https://api.anthropic.com

如果返回 HTTP/2 200 或 403（403 也行，说明能通），就没问题。如果超时，你需要配置代理。

这个坑我踩过： 我最初在公司网络环境下装，防火墙把 Anthropic 的域名墙了，折腾了一小时才发现是网络问题。如果你在国内，大概率需要配置代理，后面会讲。

第二步：获取 Claude API Key（别用错账号）

方案A：使用 Claude 官方 API

去哪里拿 Key？

1. 访问 console.anthropic.com

2. 注册/登录（注意：这是 Anthropic 的开发者控制台，不是 claude.ai 的聊天账号）

3. 点击右上角头像 → API Keys → Create Key

4. 给 Key 起个名字（比如 vscode-dev），复制保存

关键细节：免费额度与付费的区别

• 免费账号：每月 $5 额度（大约 200 万 tokens），够你测试用

• 付费账号：按量计费，Claude 4.5 Sonnet 是 百万输入，15/百万输出 tokens

我的建议： 先用免费额度跑通流程，确认真的能提升效率再充值。别一上来就充 $100，结果发现自己的开发习惯根本用不上 AI。

一个大多数教程不告诉你的坑

Anthropic 的 API Key 有两种格式：

• sk-ant-api03-xxx（新版，推荐）

• sk-ant-xxx（老版，部分功能受限）

如果你的 Key 是老格式，在 Claude Code 里可能遇到"模型不可用"的报错。解决办法：删掉旧 Key，重新创建一个。

方案B：国产替代方案——通义千问 Code Plan（国内用户优选）

如果你觉得 Claude 官方 API 的网络问题太折腾，或者不想折腾美元支付，阿里的通义千问 Code Plan 是个靠谱的替代方案。

为什么我会推荐它？

说实话，我一开始对国产 AI 编程工具是有偏见的——总觉得是套壳 GPT 或者能力不行。但通义千问 Code Plan 这个产品让我改观了：

1. 网络稳定：国内直连，不用折腾代理

2. 支付方便：支付宝/微信直接充值，不用搞美元信用卡

3. 代码能力不差：Qwen 3.5 Coder 在代码生成任务上的表现接近 Claude 4.5 Sonnet（我自己测过几个出海项目的场景，差距在 10% 以内）

4. 价格更便宜：按量计费约 ¥0.02/千 tokens，比 Claude 便宜 30% 左右

但也有缺点： 对英文技术文档的理解稍弱，如果你的项目注释和文档都是英文，Claude 会更精准。

怎么获取通义千问的 API Key？

1. 访问 dashscope.aliyun.com

2. 用阿里云账号登录（没有的话注册一个，支持手机号）

3. 进入控制台 → API-KEY 管理 → 创建新的 API-KEY

4. 复制保存（格式类似 sk-xxxxxx）

免费额度与计费

• 新用户：赠送 100 万 tokens 免费额度（够你用一个月）

• 付费：用完后按量计费，¥0.02/千 tokens（约等于 1 块钱能写 5 万行代码的量）

如何在 Claude Code 插件中使用千问 API？

重点来了： Claude Code 插件默认只支持 Anthropic 的 API，但可以通过配置"自定义 API 端点"来接入千问。

1. 安装 Claude Code 插件（步骤和官方一样）

2. 点击左侧 Claude 图标 → Settings → API Configuration

3. 找到 Custom API Endpoint，填入：

   https://dashscope.aliyuncs.com/compatible-mode/v1
   

4. 在 API Key 里粘贴你的千问 Key

5. Model 选择 qwen-coder-plus（这是千问专门优化的代码模型）

验证是否配置成功： 在 Claude 对话框随便问个问题（比如"用 Python 写个冒泡排序"），如果能正常返回代码，就说明接入成功了。

千问 vs Claude：我的真实使用感受

我在一个 Next.js 出海项目里同时用过两个模型，简单说说区别：

场景	Claude 4.5 Sonnet	通义千问 Coder Plus
生成标准 CRUD 代码	★★★★★	★★★★★（几乎无差别）
理解复杂业务逻辑	★★★★★	★★★★☆（偶尔需要多解释一遍）
英文文档理解	★★★★★	★★★☆☆（会漏掉一些细节）
中文注释生成	★★★★☆	★★★★★（更符合国内习惯）
网络稳定性（国内）	★★☆☆☆（必须代理）	★★★★★（直连无压力）
价格	★★★☆☆	★★★★★（便宜 80%）

我的建议：

• 如果你的项目主要是标准的 Web 开发（Express、Next.js、Vue 这些），千问完全够用，还省钱省心

• 如果你在做技术难度高的项目（比如 WebAssembly、复杂算法、深度优化），或者项目文档全英文，Claude 会更靠谱

• 最优解： 两个都配上，日常开发用千问，遇到复杂问题切 Claude（反正 API Key 切换只要 10 秒）

千问的一个隐藏优势

通义千问的模型训练数据里包含了大量国内开发者的代码习惯和常用框架（比如 Taro、uni-app、若依框架），如果你做的是国内市场的项目，千问生成的代码会更"接地气"。

我有次让 Claude 写个微信小程序的支付接口，它给我生成了一堆标准的 OAuth 流程，但微信支付的签名逻辑它没写对。同样的需求问千问，它直接给我生成了完整的微信支付 SDK 调用代码，连签名算法都是对的。

我的选择建议

如果你满足以下任一条件，直接用千问：

• 在国内开发，不想折腾代理

• 不想搞美元支付，嫌麻烦

• 做的是标准 Web 项目，没有特别复杂的技术需求

• 项目代码和注释主要用中文

如果你满足以下条件，用 Claude：

• 已经有稳定的国际网络环境

• 项目技术栈比较新或者比较偏门（Claude 的知识更新更快）

• 需要处理大量英文技术文档

• 对代码质量要求极高，愿意为更好的效果多花钱

最务实的方案： 先用千问的免费额度跑通流程，确认 AI 编程真的适合你，再决定要不要投入更多成本。

第三步：安装 Claude Code 插件（5 分钟搞定）

方法一：VS Code 内搜索安装

1. 打开 VS Code

2. 点击左侧扩展图标（或按 Cmd/Ctrl + Shift + X）

3. 搜索 Claude Code

4. 找到 Anthropic 官方发布的插件（作者是 Anthropic），点击 Install

方法二：命令行安装（推荐，更快）

code --install-extension Anthropic.claude-code

安装完后，VS Code 左侧会出现 Claude 的图标（一个紫色的 C）。

配置 API Key

1. 点击左侧 Claude 图标

2. 在弹出的面板里点击 Sign In

3. 选择 Use API Key

4. 粘贴你刚才复制的 Key（Claude 官方或千问的都行），回车

验证是否配置成功： 面板顶部会显示你的账号信息和剩余额度。如果显示"Invalid API Key"，检查：

• Key 是否完整复制（有些人会漏掉最后几位）

• 是否在 Key 前后多了空格

• 网络是否能访问对应的 API 端点

• 如果用千问，确认 Custom API Endpoint 填对了

第四步：写第一个 AI 辅助的代码（验证环节）

装完插件不代表能用，必须跑通一个完整流程才算成功。

场景：用 Claude 生成一个 Express 服务器

1. 新建一个文件夹 test-claude，用 VS Code 打开

2. 新建文件 server.js

3. 点击左侧 Claude 图标，在对话框输入：

帮我写一个 Express 服务器，监听 3000 端口，有一个 GET /api/hello 接口，返回 JSON 格式的 {message: "Hello from Claude"}

1. Claude 会生成代码，点击 Insert at Cursor 插入到文件

2. 终端运行：

npm init -y
npm install express
node server.js

1. 浏览器访问 http://localhost:3000/api/hello，看到返回 JSON 就成功了

这个流程在验证什么？

• Claude 能否理解你的需求（Prompt 解析能力）

• 生成的代码能否直接运行（代码质量）

• 依赖安装是否正常（Node 环境）

如果这一步失败了，99% 是前面某个环节没配对。回去检查 API Key、网络、Node 版本。

第五步：配置进阶选项（让 Claude 更懂你的项目）

1. 设置项目上下文

Claude Code 默认只分析当前打开的文件，如果你想让它理解整个项目结构，需要配置 .claudeignore 文件（类似 .gitignore）。

在项目根目录新建 .claudeignore：

node_modules/
dist/
.env
*.log

说人话就是： 告诉 Claude 哪些文件不用看，避免它把 node_modules 的几万个文件都塞进上下文，浪费 tokens。

2. 指定代码风格偏好

打开 VS Code 设置（Cmd/Ctrl + ,），搜索 Claude Code，找到 Custom Instructions，填入：

我的项目使用 JavaScript（不用 TypeScript），代码风格遵循 Airbnb 规范，注释用中文，变量命名用小驼峰。出海场景优先考虑时区处理和多语言支持。

这样 Claude 生成的代码会更符合你的习惯，不用每次都手动改格式。

3. 配置代理（国内用户必看）

如果你用的是千问 API，可以跳过这一步——千问是国内服务，不需要代理。

如果你用 Claude 官方 API，在国内需要配置代理。在 VS Code 设置里搜索 Proxy，填入你的代理地址：

http://127.0.0.1:7890

或者在终端设置环境变量：

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

我踩过的坑： 有些代理软件默认不代理终端流量，需要在代理软件设置里开启"增强模式"或"TUN 模式"。

我踩过的三个大坑

坑1：API 额度用完了还以为是 Bug

有一次我写代码写得正嗨，Claude 突然不响应了，报错"Rate limit exceeded"。我以为是插件坏了，卸载重装了两遍，最后才发现是免费额度用完了。

解决办法：

• Claude 官方：在 console.anthropic.com 的 Usage 页面能看到实时用量

• 千问：在 dashscope.aliyun.com 控制台的"资源包管理"里查看余额

如果快用完了，要么充值，要么等下个月重置。

坑2：Claude 生成的代码风格和项目不一致

我有个 Next.js 项目用的是 TypeScript + Tailwind，但 Claude 默认给我生成纯 CSS 的代码，每次都要手动改。后来我在 Custom Instructions 里写清楚技术栈，问题才解决。

教训： 别指望 Claude 自动猜你的项目配置，第一次用就把偏好写清楚，省得后面反复调教。

坑3：多文件编辑时 Claude 会"失忆"

有一次我让 Claude 修改 utils.js 里的一个函数，然后切到 api.js 让它调用这个函数，结果 Claude 说"找不到这个函数"。

原因： Claude Code 的上下文窗口有限，如果你频繁切换文件，它会丢失之前的修改记录。

解决办法： 在一个对话里尽量把相关文件的修改说清楚，或者用"请同时修改 utils.js 和 api.js"这种明确的指令。

总结：安装只是开始，用对才是关键

装完 Claude Code 不代表你就能"AI 编程"了，就像买了健身卡不代表你能练出腹肌。

核心判断： Claude Code 不是用来替你写代码的，而是用来加速你已经知道怎么做的事情。如果你连基本的 Web 开发概念都不懂，AI 生成再多代码你也看不懂为什么能跑、为什么会报错。

装完这套流程，你应该能做到：

• 30 秒生成一个标准的 API 接口

• 5 分钟完成重复性的 CRUD 代码

• 遇到不熟悉的库时，让 Claude 先写个 demo 再自己改

但别指望它能帮你做架构设计、性能优化、复杂的业务逻辑——那些还得靠你自己。

---

你遇到过哪些安装或配置的坑？

留言区说说你第一次用 Claude Code 时卡在哪了，或者有什么我没提到的细节问题。如果超过 3 个人遇到同一个坑，我会单独写一篇排查指南。

另外，如果你用过千问和 Claude 两个方案，也欢迎分享你的真实对比感受——到底哪个更适合国内开发者，我也想听听大家的反馈。