老规矩，先把话说清楚：这篇不聊任何网络连接层面的东西，只聊工具本身的安装、配置、上手和避坑。中文社区里“国内怎么用 Claude Code？”这个问题问得很多，但工具真正拿到手之后，卡住人的往往不是那些外部因素，而是使用方式没切换过来。Claude Code 不是网页对话框的终端版，而是跑在你项目目录里的编码代理。它能读文件、跑命令、直接改代码，也能当作结对程序员一起做重构、补测试、理逻辑。这篇文章写给已经拿到使用权限、准备在真实项目里落地的人，也会照顾第一次接触终端 AI 工具的读者。
1. 先搞清楚 Claude Code 到底是什么
1.1 它和聊天式 AI 的根本区别
用过网页版 Claude 的朋友可能会想：不就是把对话窗口搬进终端吗？真不是。
网页聊天更像一个军师，你描述问题，它给你思路和代码片段，你自己复制粘贴到编辑器里。Claude Code 更像一个坐在你工位旁边的实习生，你给它目标，它会在当前项目目录里自己看文件、查代码、执行命令、修改文件，然后把结果汇报给你。
这个区别带来两个重要变化：
- 它的输出是“已经写进项目里的改动”，不是“给你一段参考代码”。
- 它需要你在关键节点给反馈，而不是甩一句话就结束。
我第一次跑起来的时候，让它修复一个 bug，它直接定位到源码、改了代码、跑了测试，然后把 test output 贴在对话里。那种感觉不是惊艳，是后背发凉——它的权限确实很大。所以后面我会反复强调一个原则：永远让它在一个 git 分支里干活，永远用 diff 审查它的改动。
1.2 它适合做什么，不适合做什么
用了一段时间，我给它总结了三类最合适的任务：
第一类是“找线索”型任务。比如打开一个陌生项目，让它解释目录结构、核心数据流、关键入口，比人肉翻代码快得多。
第二类是“重复劳动”型任务。比如给几十个函数补充 docstring、统一 import 顺序、批量替换过时 API，这种活它做起来又快又稳。
第三类是“测试与重构”型任务。比如给现有代码补单元测试、提取公共函数、调整模块边界，它能在你不熟悉的代码里快速形成全局认知。
但也有三类场景我会刻意避开：
- 没有明确验收标准的探索。你都不知道想要什么，它也做不出什么。
- 涉及敏感权限的关键操作。比如生产库迁移、密钥轮换，不能直接甩给它。
- 需要长期架构视野的决策。它能当很好的参谋，但最终拍板必须是人。
简而言之，Claude Code 适合当“放大你能力的执行层”，不适合当“替你做判断的决策层”。
2. 本地环境准备：先给它一个能跑的地盘
2.1 硬性前置条件
Claude Code 本质是一个 Node.js 的命令行程序，所以在安装它之前，你得先确认机器上有可用的 Node.js 环境。核心条件就三个：
- 一台可联网的电脑（这里不进一步展开）
- Node.js 18 或更新的 LTS 版本
- 一个能跑 Bash 命令的终端环境
- 一组有效的访问凭证（API Key 或已登录账号）
很多安装问题都不是 Claude Code 本身的锅，而是 Node.js 版本太老。建议先打开终端，执行两条命令看看：
node -v npm -v如果第一条输出类似v18.20.0这种，说明 Node 可用。如果提示找不到命令，或者版本低于 18，就先去装 Node.js。
2.2 Node.js 安装的几种方式和版本管理
Node.js 安装不复杂，但不同系统有不同讲究。
macOS 上如果装了 Homebrew，一条命令搞定：
brew install nodeWindows 上比较推荐直接用官方安装包，一路 Next 就行。不过我更建议在 Windows 上顺手把 Windows Terminal 和 Git Bash 配好，因为 Claude Code 的命令行交互体验在这些环境里更顺滑。
Linux 用户别用系统自带的旧版本，建议通过包管理器装新版，或者用 nvm 按项目切换版本。
这里要着重说一下 nvm（Node Version Manager）。我用 nvm 的原因很简单：它会帮我把 Node 安装在用户目录下，不需要 sudo，也不再遇到 npm 全局安装时的 EACCES 权限错误。如果你打算长期用 Claude Code 和各种前端工具，nvm 几乎是必备品。
# 安装 nvm 后 nvm install 20 nvm use 20装完 nvm，Node 和 npm 都会指向用户目录里的版本，之后全局安装工具基本不会再碰到权限问题。
3. 安装 Claude Code 并完成首次启动
3.1 用 npm 安装官方包
环境准备好后，安装本身并不复杂。Claude Code 的官方 npm 包名是@anthropic-ai/claude-code，在终端执行：
npm install -g @anthropic-ai/claude-code加-g是全局安装，因为命令claude需要放到系统 PATH 里。
安装完成后，先确认一下版本：
claude --version如果终端返回版本号，说明安装成功。如果提示claude: command not found，多半是因为 npm 全局 bin 目录不在 PATH 里。最省事的解决办法是用 nvm 重装 Node，因为 nvm 会自动配置 PATH。
3.2 配置访问凭证
第一次运行前，还需要让 Claude Code 知道你是谁。通常在首次启动时会走进一个授权流程，跟着提示操作即可。更可控的方式是手动配置环境变量。
在 macOS / Linux 的终端里：
export ANTHROPIC_API_KEY="你的密钥"Windows PowerShell 里则写成：
$env:ANTHROPIC_API_KEY="你的密钥"注意，这种方式的变量只在当前终端窗口有效。关掉窗口再打开，环境变量就没了。所以更推荐写进 shell 配置文件里。
比如在~/.zshrc或~/.bashrc中加一行：
export ANTHROPIC_API_KEY="你的密钥"然后执行：
source ~/.zshrc我踩过的一个坑是：密钥复制过来时带了换行或者空格，认证会一直失败。所以配置完可以用一个简单的命令检查：
echo $ANTHROPIC_API_KEY确保输出的内容和你预期的密钥完全一致。
3.3 首次启动验证
配置好密钥后，建议不要直接在项目目录里开始干活，先到任意一个临时目录做一次冒烟测试。
创建一个空目录，进去后运行：
claude启动成功以后，它通常会输出一段欢迎信息，并可能询问当前目录是否在项目内、要不要扫描文件等。由于临时目录里什么都没有，你可以输入一个极其简单的指令：
回复“ok”来确认你还能正常工作等它正常回复之后，说明安装、认证、基础链路全部打通。然后再回到真实项目目录里去使用。这个验证步骤看着很笨，但真的能排除很多后续问题。
4. 核心使用方式：像带实习生一样带它
4.1 两种常用的启动模式
Claude Code 最常用的是交互式模式，也就是在项目目录直接运行：
claude这会进入一个多行对话界面，适合持续来回沟通，一边看它的改动一边追问和调整。
另一个很有用的模式是一次性任务模式，适合写脚本或者在 CI 场景中调用：
claude -p "给 src/utils.ts 中所有导出函数补充 JSDoc 注释"-p是 print 模式，执行完任务后直接输出结果然后退出，不会挂起一个交互界面。你也可以在脚本里循环调用它来处理批量任务。
根据我个人的实践，刚开始别太依赖-p模式，先在交互式模式下把一个任务完整走一遍，感受它改文件和执行命令的习惯。等摸清规律之后，再把它接进自动化流程。
4.2 让它待在正确的项目上下文里
Claude Code 最大的优势之一是能读取当前目录下的文件。但如果目录选错了，这个优势会变成劣势。
我第一次在用户主目录运行它，结果它读了一堆乱七八糟的配置文件，上下文被大量无用信息占满，回答质量明显下降。后来养成习惯：每次使用前，先cd到对应的 git 仓库根目录，再启动。
还有一个实用技巧：在项目根目录放一个CLAUDE.md文件，把项目约定写进去。Claude Code 启动时会自动读取这个文件，相当于给 AI 一份“员工手册”。
举个例子，一个常见的前端项目可以写：
# 项目约定 - 使用 TypeScript，禁止 any - 测试命令：npm run test - 构建命令：npm run build - 代码风格遵循 standardjs - src/components 下只放无业务逻辑的 UI 组件有了这份手册，它对你的项目了解程度会明显提升。这个文件不需要写多长，重点是把新成员上岗第一天需要知道的规则写清楚。
4.3 下达修改任务的正确姿势
给它的指令越模糊，它就越容易发挥。但项目代码不是想象力的游乐场，所以我会用四段式来提需求：
- 目标：要解决什么问题，验收标准是什么。
- 范围：允许动哪些目录和文件，禁止动哪些。
- 约束：有哪些技术限制，比如不能加新依赖。
- 验证：改完之后跑什么命令来确认。
一个具体例子：
请修复登录接口在密码错误时返回 500 的问题。 范围：只允许修改 backend/auth.py 和 backend/views.py。 约束：不要改动数据库表结构，不要引入新依赖。 验证：修改完成后运行 pytest tests/test_auth.py。这个 prompt 看起来不惊艳，但实际效果比“帮我修一下登录 bug”强十倍。因为它给了 AI 一个明确的搜索区间，避免它在全代码库里乱逛。
另外，每次执行完改动，我都会先跑git diff看看它到底改了什么。
git diff --stat git diff很多次它改的确实能跑，但风格可能不是你想要的。这时候不用着急打回，直接在对话里告诉它“这里用单例而不是全局变量”“命名风格改成 UserService 而不是 user_svc”，它能很快调整。
5. 容易被忽略的配置项和实操技巧
5.1 权限控制：别一上来就全场放行
Claude Code 在执行命令或改文件时会有权限机制。有些用户为了方便，会直接使用跳过权限确认的选项。我的建议是：只在隔离环境或容器里用，本地开发时不要开。
权限确认虽然烦琐，但它就像安全门禁，每道门都在提醒你“这里动的是真实项目”。我见过一个同行因为一直放行，让它顺手改了依赖锁文件，结果整个项目的依赖版本被更新，半天时间花在回滚上。
更稳妥的做法是，让它在默认权限模式下工作。遇到它需要执行某个命令时，你会收到确认提示，这时你有机会判断这个命令是否安全。偶尔多敲几次 y，总比事后修代码省事得多。
5.2 用 CLAUDE.md 固化项目记忆
前面提到过在项目根目录放CLAUDE.md，这里再展开一些。
Claude Code 每次启动都会读取这个文件，相当于给每次会话注入长期记忆。如果你发现同一个问题要反复跟它解释，或者它总是忘记你的测试命令，那说明你需要把规则写进这个文件里。
一个相对完整的模板可以包含：
- 项目技术栈和核心目录说明
- 常用的开发、测试、构建命令
- 代码风格和质量要求
- 项目中容易出现误操作的地方
这个文件应该由人维护，建议随代码一起进 git 仓库。这样团队成员都能分享同一套 AI 协作规则。原则是：它不需要写满一百条，但每一条都要在执行层面可验证。
5.3 与 Git 协同的正确节奏
Claude Code 直接改文件，所以 git 天然是主力保护伞。我会遵循这么一套流程：
启动前，先确保分支是干净的：
git status如果当前分支有未提交的改动，先提交或 stash，不要带着脏分支让它干活。不然 diff 里混着你和它的改动，很难区分。
任务开始前，我会新建一个专门的分支：
git checkout -b ai/refactor-login然后在这个分支上放开手让它折腾。任务完成后，先用git diff检查，再执行测试，最后手动提交。如果改得不行，直接git checkout -- .就能回到干净状态。
为什么特别强调这一点？因为 AI 改代码失败的时候通常不是直接报错，而是看起来“好像改对了”。分支和 diff 给了你低成本查看和回滚的空间。不要依靠它自己保持“记忆”，要靠 git 保持可恢复性。
6. 常见问题与排查经验
我把自己实际使用中遇到过的、以及在几个技术群里看到的高频问题整理成了一个速查表。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 安装时报 EACCES 权限错误 | npm 全局目录没有写权限，或使用 sudo 方式 | 用 nvm 管理 Node，让全局包装到用户目录 |
命令找不到claude | npm bin 目录不在 PATH 中 | 检查 PATH；如果使用 nvm，重装 Node 并重新开终端 |
| 提示认证失败 | API 凭证配置错误，或者环境变量未生效 | 检查密钥前后有无空格；用echo确认变量；重新加载 shell 配置 |
| 回复内容很空，像没看过代码 | 在错误的目录里启动，项目文件未被读取 | 进入项目根目录后重新启动，确认目录下有文件 |
| 输出中文乱码 | 终端或系统 locale 不支持 UTF-8 | 确认终端的编码为 UTF-8 或 UTF-8 with BOM |
| 响应特别慢 | 项目目录里有大量无关文件，导致上下文过大 | 确保.gitignore排除 node_modules、dist 等目录；必要时设置忽略规则 |
| 改动波及范围出乎意料 | prompt 里没有限定修改范围 | 使用四段式 prompt，明确文件范围和约束 |
6.1 安装后命令不可用
如果你装了 nvm 后仍然找不到claude，先执行：
npm prefix -g这个命令会输出 npm 全局安装目录，检查该目录是否在 PATH 中。如果不在，可以把$(npm prefix -g)/bin加到 shell 配置文件的 PATH 里。这比盲目重装系统有效。
6.2 中文输出乱码
这个坑在 Windows 上尤其容易出现。Claude Code 输出的是 UTF-8，但 Windows PowerShell 老版本默认编码可能不是 UTF-8，导致中文显示成乱码。解决办法是在启动前设置：
chcp 65001或者直接在 Windows Terminal 的设置里把默认编码调整为 UTF-8。macOS 和 Linux 一般很少遇到这种问题。
6.3 上下文被无关文件污染
一个大型项目里往往有海量文件，如果 Claude Code 一股脑把无用内容读进去，输出质量就会下降。它默认会参考 git 的忽略规则，所以保证.gitignore写得完整是基础操作。
此外，不要在一个巨型 monorepo 的根目录运行它，除非你真的需要全局视角。很多时候把范围缩小到子模块，效果反而更好。比如只处理packages/auth下的代码，就先进到那个目录，再启动 Claude Code。
最后再分享一点我个人的体会
用了这么久的 Claude Code，我的核心感受是：它不是来替代人的，而是把人从“找文件、读上下文、做重复修改”的体力活里解放出来。但这份解放是有代价的——你必须具备更强的判断力、更清晰的指令表达和更严格的分支管理习惯。
如果你是这个工具的新手，我建议不要在第一个任务上来就来“帮我重构整个项目”。挑一个边界清楚、验收标准明确的模块，比如“给某个接口补参数校验”，完整跑一遍体验一下它的工作方式。等它的行为模式你熟悉了，再慢慢扩大任务范围，会让整个协作过程可控得多。
一个小技巧：给它写的任务说明，可以当成自己新同事入职第一天收到的任务清单来写。边界定得清楚，背景交代明白，验收方式说透，它能给你的回报往往远超预期。
