Claude Code 部署使用教程：我踩过的坑都在这了
说实话，我一开始对 Claude Code 这玩意儿是不太感冒的。命令行编程助手？听起来就不如 Cursor 那种有图形界面的来得舒服。但真正用起来之后，我只能说——真香。它跟 Copilot 完全不是一个量级的东西，它能直接读懂你整个项目，然后自己动手改代码、跑测试、提交 Git，活脱脱一个不睡觉的高级工程师。
我把这段时间折腾 Claude Code 的经历整理出来，包括我踩过的各种坑，希望对大家有帮助。
一、这东西到底是个啥
先搞清楚一个事：Claude Code 不是聊天机器人。你跟 ChatGPT 聊天，它给你代码片段，你自己复制粘贴。Claude Code 不一样，你给它一句话描述任务，它自己去读你的项目结构，理解文件之间的依赖关系，然后直接上手改代码。改完了还会问你同不同意，你点头它就执行。
它能干啥呢？读文件、写代码、跑命令、管理 Git、执行测试，基本上你在终端里能干的活它都能帮你干。关键是它有上下文，不是改了这个文件就忘了那个文件，它能看懂你整个项目的架构。
二、安装踩坑记录
2.1 正常安装
官方现在推荐用 Native 安装方式，不再建议用 npm 了。macOS 和 Linux 用户直接一行命令：
| 1 | |
Windows 用户用 PowerShell（注意是 PowerShell，不是 CMD）：
| 1 | |
macOS 还能用 Homebrew：
| 1 | |
2.2 我踩的坑
坑一：PowerShell 和 CMD 搞混。 我第一次在 Windows 上装的时候，在 PowerShell 里敲了 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd，直接报错 The token '&&' is not a valid statement separator。后来才搞明白，PowerShell 的提示符是 PS C:\>，CMD 的是 C:\>，长得不一样，别搞混了。
坑二：npm 安装时 Node.js 版本太低。 如果你非要用 npm 安装，记得先检查 Node.js 版本，低于 v18.0 会出问题。我用 Ubuntu 的 apt 装的 Node.js 版本才 12，升级用了 sudo npm install -g n && sudo n stable 才搞定。另外建议配一下国内 npm 镜像，不然下载慢到怀疑人生：
| 1 | |
坑三：Native 安装和 WinGet 安装的区别。 我一开始不知道，用 WinGet 装的，后来发现它不支持自动更新，每次要手动 winget upgrade。Native 安装可以自动更新，但卸载得手动删文件夹。看你需求选吧。
三、登录和启动
装好之后，进到你的项目目录，直接敲 claude 就能启动。第一次会提示你登录。
账号类型有好几种：Claude 订阅（Pro、Max、Team、Enterprise）、API 密钥、或者云厂商的服务（Amazon Bedrock、Google Vertex AI 之类的）。
地域限制问题
这个是国内用户大概率会遇到的。我启动之后直接提示地域限制，折腾了一圈才知道，要去改 ~/.claude.json 这个文件，加上：
| 1 | |
| 2 | |
| 3 | |
加完之后就好了，跳过引导流程直接用。Windows 用户的路径是 C:\Users\你的用户名\.claude.json。
四、接入第三方模型（省钱重点）
直接用 Claude 官方的 API，说实话挺贵的。国内用户建议接入国内的模型服务，便宜很多，效果也不差。
方案一：cc-switch 图形化工具
cc-switch 是一个桌面应用，可以管理和切换 Claude Code 用的后端模型。去 GitHub（https://github.com/farion1231/cc-switch）下载对应平台的安装包就行。
装好之后，你需要一个 API Key。比如去魔搭社区（https://modelscope.cn/），注册绑定阿里云账号，在访问控制页面创建一个令牌。然后在 cc-switch 里选供应商、填 API Key、选模型，三步搞定。
推荐几个模型：
- 编程用：
Qwen/Qwen3-Coder-480B-A35B-Instruct，目前魔搭上最大的编程模型 - 推理用：
Qwen/Qwen3-235B-A22B-Thinking-2507 - 通用：
qwen3.5-plus、glm-4.7、kimi-k2.5
方案二：阿里云百炼 Coding Plan（我目前在用的）
这个方案配置最简单，而且按请求计费，不会浪费 Token。新用户首月最低 7.9 块钱，18000 次请求，够用了。
步骤：
- 去百炼控制台：
https://bailian.console.aliyun.com/cn-beijing/?tab=model#/efm/coding_plan - 买个套餐，Lite 版首月 7.9 元，Pro 版 39.9 元
- 生成 API Key
然后编辑 ~/.claude-code/setting.json：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
记得 ~/.claude.json 里也要有 "hasCompletedOnboarding": true。
接入之后，在 Claude Code 里直接 /model qwen3.5-plus 就能切换模型，支持 qwen3.5-plus、qwen3-coder-next、glm-4.7、kimi-k2.5 这些。
踩坑提醒： API_TIMEOUT_MS 一定要设大一点，我一开始没设，结果稍复杂的任务就超时了，设成 3000000（3000 秒）就稳了。
五、日常使用技巧
5.1 项目初始化（必做！）
进到项目第一件事，敲 /init。Claude Code 会通读你的项目，生成一个 CLAUDE.md 文件。以后每次执行任务它都会先看这个文件，相当于给它一份项目说明书。
你也可以自己往 CLAUDE.md 里加东西，比如技术栈、代码规范、目录结构约定。这一步真的非常影响效果，我有个项目没写 CLAUDE.md，AI 经常猜错技术方案，写了之后准确率直接上了一个台阶。
5.2 三种工作模式
按 Alt+M 切换：
- 普通模式：AI 改完代码要你确认才执行，最安全
- Auto Accept 模式：AI 直接改，不问你。适合信任度高的批量操作
- Plan 模式：AI 只出方案不动手，适合复杂任务先规划
我的经验： 先用 Plan 模式让 AI 列出执行计划，看看思路对不对，确认了再切普通模式执行。千万别上来就 Auto Accept，改错了回退很麻烦。
5.3 控制思考深度
这个挺有意思的，在提问前面加关键词能让 AI 想得更深：
think: 分析这个函数的性能问题think hard: 这个算法的时间复杂度如何优化think harder: 重构整个支付模块的架构ultrathink: 设计一个支持百万并发的消息队列系统
思考深度依次递增，简单任务别加这些，费 Token。
5.4 省 Token 技巧
/compact：压缩对话历史，一段任务聊完了就压缩一下/clear：清空对话，开始新任务- 简单问题用轻量模型，复杂问题才上大模型
- 写好
CLAUDE.md，减少 AI 猜测
5.5 其他好用的功能
- 在对话里输入
!ls -la、!npm test这种带!前缀的命令，可以直接执行 Shell 命令，输出还会自动加入 AI 的上下文 - 支持拖图片进去，分析 UI 截图、架构图很方便
- 装个 VS Code 插件，输入
/ide连接，AI 改的代码会以 diff 的形式展示在 VS Code 里
六、常见问题
装完启动不了？ 检查 Node.js 版本 ≥ v18，网络能访问安装源，Windows 用户确认用的对端。
模型调用失败？ API Key 有没有填对，BASE_URL 有没有写错，模型名字有没有拼错，超时时间设够了没。
Token 消耗太快？ 养成用 /compact 的习惯，CLAUDE.md 写详细点。
七、常用命令速查
启动：claude（交互模式）、claude "fix the build error"（一次性任务）、claude -p "explain this function"（查询后退出）
会话内：/init（初始化项目）、/compact（压缩对话）、/clear（清空对话）、/model xxx（切换模型）、/login（切换账号）、/ide（连 VS Code）、exit 或 Ctrl+D（退出）
八、最后说几句
Claude Code 真的不是那种花架子工具，它确确实实能提升编程效率。我现在的日常就是：Plan 模式让 AI 先规划，确认思路没问题了切普通模式执行，一段任务结束就 /compact 压缩一下。配合百炼 Coding Plan，一个月花不了多少钱，但省下来的时间是实打实的。
如果你还没试过，建议花半小时装一下，找个小项目体验体验。相信我，用过之后你就回不去了。