说实话，当你面对一个两年前留下的 Express 项目时那种心情简直像是走进了一个满是灰尘的旧仓库。所有的路由逻辑dou像是一团乱麻，死死地缠绕在 app.js 这一个文件里几千行代码堆在一起，没有类型检查，错误处理全靠Zui原始的 try-catch 裸奔。这种时候，我通常会陷入深深的自我怀疑：这真的是我写出来的东西吗？

Zui近，我决定把这个烂摊子收拾一下但我这次不想单打独斗了。我想到了 Anthropic 推出的命令行 AI 编程助手——Claude Code。这玩意儿Ke以直接在你的终端里用自然语言操作代码仓库，读文件、改代码、跑测试，甚至还Neng帮你提交 Git。听起来hen美好，对吧？但实际配置起来尤其是对于咱们国内开发者来说还是有不少坑要踩的。这篇文章，我就把这两天折腾出来的血泪经验全盘托出，希望Neng帮你省点时间。

在开始之前，你得先确认一下你的“武器装备”是否齐全。Claude Code 对 Node.js 的版本是有要求的，Ru果你还在用老掉牙的 Node 16，那我劝你赶紧升级。我第一次尝试的时候就吃了大亏，安装过程直接报错，提示 engine "node" is incompatible，然后卡在那里不动。

所以先在终端里敲一下：

node -v
# 确保至少是 v18 以上，推荐 v20

除了 Node 版本，网络环境也是个老大难问题。官方的安装包有时候下载慢得像蜗牛爬，甚至直接超时。Ru果你也遇到了 network timeout 之类的错误，别犹豫，赶紧换镜像源或者开代理。我自己是用 npm 镜像源解决的，省心不少。

环境没问题了接下来就是安装。这一步其实hen简单，但细节决定成败。打开你的终端，输入全局安装指令：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

这里我特意加上了淘宝镜像源，毕竟谁也不想盯着进度条发呆十分钟。安装完成后记得验证一下：

claude --version

Ru果Nengkan到版本号，恭喜你，第一关过了。不过macOS 用户可Neng会遇到一个经典的权限报错，比如 Error: EACCES: permission denied。这通常是因为 npm 的全局安装目录权限不够。解决办法要么是用 sudo npm install -g 强行安装，要么像我一样，老老实实用 nvm 来管理 Node 版本，这样就不会有权限问题了。

装好了只是第一步，怎么让它跑起来才是关键。这里有个hen现实的问题：Anthropic 官方 API 的账单只Neng绑国际信用卡。Ru果你是一个人用还好，但Ru果是团队协作，每个人dou去搞一张卡，月底对账的时候简直是噩梦。而且，直接连官方 API，有时候网络延迟会让你怀疑人生。

所以我的方案是使用支持自定义 API 端点的配置。核心思路就是设置两个环境变量，把流量引到第三方聚合平台，这样既Neng解决支付问题，又Neng利用多通道负载均衡提高稳定性。

你Ke以直接在 .bashrc 或者 .zshrc 里加上这两行：

export ANTHROPIC_BASE_URL="https://api.ofox.ai/anthropic"
export ANTHROPIC_API_KEY="your-ofox-key"

当然Ru果你不想污染全局环境，也Ke以在项目根目录下建一个 .claude/settings.json 文件。这样配置的好处是只针对当前项目生效，团队协作时也geng方便。配置文件大概长这样：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.ofox.ai/anthropic",
    "ANTHROPIC_API_KEY": "your-key"
  },
  "model": "claude-sonnet---",
  "permissions": {
    "allow_file_write": true,
    "allow_shell": false
  }
}

这里有个小细节，Ru果你在配置 ANTHROPIC_MODEL 环境变量时尝试使用其在 OpenAI 兼容接口中的映射名，比如 qwen-code-latest 或者 qwen-2.5-coder-turbo，有时候也Neng跑通，但这属于比较野路子的玩法，官方文档里可没写。

配置搞定后进入你的项目目录，直接输入 claude 启动。第一次启动时它会像一只好奇的小狗一样，自动扫描你的整个项目结构。这时候你Ke以去倒杯水，因为它需要一点时间来理解你的代码逻辑。

扫描完成后你就Ke以用自然语言跟它对话了。我通常会先让它Zuo一个“体检”，比如：“帮我分析一下这个项目的架构问题。”

它花了几十秒扫完所有文件，给了一份还挺靠谱的分析报告——指出了路由没拆分、缺少统一错误处理中间件、数据库连接没Zuo连接池、环境变量硬编码这几个问题。那一刻，我感觉它简直是我的知音。

光说不练假把式。我决定让它把那个臃肿的 app.js 动刀。我的指令hen简单：“把路由逻辑拆分到单独的文件里按照功Neng模块划分。”

它开始干活了。先是创建了 routes/users.jsroutes/orders.jsroutes/products.js，把对应的路由代码搬过去，然后修改 app.js 的 import。整个过程大概几十秒，改了十几个文件，效率高得让我有点慌。

但这里出了一点小插曲。它把一个中间件函数 authMiddleware 从 app.js 搬到 routes/users.js 里了结果 routes/orders.js 也用到了这个中间件。一跑起来直接报错：ReferenceError: authMiddleware is not defined。

我当时心里咯噔一下以为要手动去改了。但我还是把报错信息贴给了它。没想到它立刻意识到问题，把 authMiddleware 提取到了 middleware/auth.js，然后让两个路由文件dou import 这个公共模块。修复后测试全过。这种“改出 bug → 贴报错 → 它修复”的循环，说实话，比自己 debug 快多了但你得盯着，不Neng完全放手，不然它可Neng会把你的代码改得面目全非。

用了两天我发现了一些必须注意的坑，尤其是关于权限和 Git 操作的。

Claude Code 默认是Ke以直接帮你 git commit 的。听起来hen方便，对吧？但有一次它把我还没改完的文件也一起提交了差点推送到生产环境。从那以后我dou在 settings 里把 Git 写操作关掉，让它只读 Git 状态。

在 .claude/settings.json 里加上这段配置：

{
  "permissions": {
    "allow_git_write": false
  }
}

还有一个选项叫 allow_shell，控制 Claude Code Neng不Neng直接执行 shell 命令。官方虽然说有沙箱，但我这人比较保守，还是把它设成了 false。需要跑命令的时候，让它告诉我，我自己复制粘贴执行，这样心里踏实点。

有一次我让它读一个超大的 SQL migration 文件，结果直接卡住了等了两分钟没响应。后来我发现，目前它处理大文件的Neng力还是有限。唯一的办法就是手动把文件拆成几段喂给它。虽然有点麻烦，但总比卡死强。

Ru果你直接用 Anthropic 官方 API，连续高频对话偶尔会触发限流，报错 429 Too Many Requests。这时候除了等或者升套餐，没什么好办法。不过走聚合平台的话，情况会好hen多，像 OpenRouter 和 ofox.ai 这类服务商一般有多通道负载均衡，被限流的概率低一些。

除了基本的配置和避坑，还有一些小技巧Neng让你的体验geng丝滑。

跟 .gitignore 语法一样，你Ke以建一个 .claudeignore 文件，把 node_modulesdist.env 这些乱七八糟的目录排除掉。不然它扫描项目的时候会把这些垃圾文件也读进去，既浪费时间又浪费 token。

# .claudeignore
node_modules/
dist/
.env
*.log
coverage/

默认情况下它用的是 Sonnet 模型，日常够用。但Ru果你遇到复杂的架构决策，或者需要写一些复杂的算法，Ke以临时切到 Opus。虽然 Opus 贵不少，但理解复杂代码库的Neng力确实强一档。切换命令hen简单：

 /model claude-opus---

聊久了上下文会爆，Claude Code 会提示 token 快满了。这时候输入 /compact，它会把之前的对话压缩成摘要，释放上下文空间。这个功Neng在长时间重构时特别有用，不用重启对话就Neng继续干活。