1. 环境准备与基础依赖梳理
1.1 为什么 Node.js 是绕不开的第一道坎
Claude Code 这个 CLI 工具本质上是跑在 Node.js 运行时上的一个命令行程序，所以不管你用 Windows、macOS 还是 Linux，第一步都得先把 Node.js 装好。很多人卡在第一步不是因为不会装，而是版本选错了。我实测下来，Node.js 18 是最低门槛，20 LTS 或 22 LTS 才是舒服的区间。网上有人反馈node.js 18 the requested module 'node:util' does not provide an export named这类报错，基本就是版本太老或者装了个非 LTS 的奇怪版本导致的。
你可以把 Node.js 理解成“让 JavaScript 能脱离浏览器、直接在电脑上跑起来的一个引擎”。Claude Code 的安装脚本、依赖包、启动逻辑全靠它。没有它，后面所有步骤都是空中楼阁。
安装方式我推荐两种：
- 官网下载安装包：直接搜“node.js 官网下载”，选 LTS 版本，一路下一步。Windows 用户注意勾选“Add to PATH”，否则命令行里敲
node -v会提示找不到命令。 - 包管理器安装：macOS 用
brew install node，Linux 用apt或nvm。我个人更推荐nvm，因为可以随时切换版本，遇到兼容问题不用重装系统。
装完之后验证一下：
node -v npm -v两条命令都能输出版本号，说明环境通了。如果npm报错，多半是 PATH 没配好，重启终端或者手动加一下环境变量即可。
提示：不要用系统自带的旧版 Node.js，尤其是某些 Linux 发行版预装的版本，往往低于 18，会直接导致 Claude Code 启动失败。
1.2 安装 Claude Code CLI 的两种路径
环境好了之后，安装 Claude Code 本身其实很快。官方主推的是 npm 全局安装：
npm install -g @anthropic-ai/claude-code这条命令做完，你的终端里就多了一个claude命令。敲claude --version能看到版本号，就说明 CLI 已经就位。
另一种是下载客户端或桌面版，适合不习惯命令行的朋友。但我要说句实在话，Claude Code 的核心价值就在 CLI 里，桌面版功能相对受限，而且后续配置环境变量、切换模型这些操作，CLI 更灵活。所以如果你是想长期用，建议直接走 CLI 路线。
安装过程中常见的坑：
- 权限报错：macOS/Linux 下全局安装可能需要
sudo，但我不建议直接sudo npm install -g，容易把 npm 目录权限搞乱。更好的做法是配置 npm 的全局目录到用户目录下。 - 网络超时：npm 默认源在部分网络环境下会慢，可以临时切到国内镜像源，装完再切回来。
- 安装后命令找不到：说明 npm 全局 bin 目录没在 PATH 里，用
npm config get prefix看一下路径，手动加进环境变量。
1.3 卸载与重装的正确姿势
有时候装崩了，或者想换版本，得先卸干净。命令是：
npm uninstall -g @anthropic-ai/claude-code但光这样不够，配置文件和缓存还留在用户目录里。macOS/Linux 下通常在~/.claude或~/.config/claude，Windows 在%USERPROFILE%\.claude。如果你遇到“重装后还是老样子”的情况，八成是旧配置没清。我的习惯是卸载后手动把配置目录改名备份，再重装，这样最干净。
2. 核心配置解析：BASE_URL 与 AUTH_TOKEN
2.1 两个环境变量到底管什么
Claude Code 要能跑起来，核心就两个环境变量：
ANTHROPIC_BASE_URL：告诉 CLI 去哪里找模型服务。ANTHROPIC_AUTH_TOKEN：告诉服务“我是谁”，用来鉴权。
你可以把它们理解成“快递地址”和“门禁卡”。地址不对，包裹送不到；门禁卡不对，门都进不去。很多人配置完发现一直转圈或者报鉴权错误，基本都是这两个值写错了。
设置方式分临时和永久两种。临时的话直接在终端里：
export ANTHROPIC_BASE_URL="你的服务地址" export ANTHROPIC_AUTH_TOKEN="你的令牌"Windows PowerShell 用$env:ANTHROPIC_BASE_URL="..."。但这样关掉终端就没了，所以长期用建议写进 shell 配置文件，比如~/.zshrc或~/.bashrc，Windows 则写进系统环境变量。
注意：网上有个高频报错
both anthropic_auth_token and anthropic_api_key set 路 auth may not work as，意思是同时设置了 token 和 api_key，导致鉴权逻辑冲突。解决办法很简单，只保留一个，把另一个删掉或注释掉。
2.2 配置文件的写法与优先级
除了环境变量，Claude Code 也支持配置文件。一般放在~/.claude/settings.json或项目根目录下的.claude/settings.json。写法大致是：
{ "env": { "ANTHROPIC_BASE_URL": "你的服务地址", "ANTHROPIC_AUTH_TOKEN": "你的令牌" } }优先级上，项目级配置 > 用户级配置 > 系统环境变量。这个顺序很重要，因为有时候你在系统里设了变量，但项目里有个旧配置文件把它覆盖了，就会莫名其妙不生效。排查问题时，先看项目目录下有没有.claude文件夹。
我个人的习惯是：全局环境变量放通用配置，具体项目用项目级配置覆盖。这样切换项目时不用反复改系统变量。
2.3 验证配置是否生效
配完之后别急着写代码，先验证。最直接的办法是启动 Claude Code，随便问一句“你好”，看它能不能正常回复。如果报错，按下面的顺序排查：
echo $ANTHROPIC_BASE_URL看变量是否真的存在。- 检查 token 有没有多余空格或换行。
- 确认没有同时设置
ANTHROPIC_API_KEY。 - 看配置文件是否被正确加载。
我踩过最坑的一次是复制 token 时带了个换行符，肉眼完全看不出来，排查了半小时。后来养成习惯，设置完用echo打印出来核对一遍。
3. 实操跑通：从启动到第一个任务
3.1 首次启动与初始化流程
配置就绪后，在终端里进入你的项目目录，敲：
claude第一次启动会有一个初始化过程，可能会让你确认一些权限、选择主题或者登录方式。如果你已经配好了环境变量，一般会直接进入交互界面。界面上会显示一个输入框，你可以直接用自然语言描述任务，比如“帮我读一下这个项目的结构”或者“给这个函数写个测试”。
这里有个细节：Claude Code 默认只在你当前打开的目录及其子目录里活动。所以启动前先cd到正确的项目根目录，不然它找不到文件，会一直问你路径。
3.2 给足访问权限的正确方式
很多人第一次用会发现 Claude Code“畏手畏脚”，读个文件都要问一次权限。这是因为默认权限比较保守。想让它顺畅干活，需要给它完全访问权限。常见做法是启动时加参数：
claude --dangerously-skip-permissions这个参数的意思是跳过每次操作的权限确认。名字听着吓人，但如果你在自己的开发机上、项目目录也明确，用起来效率会高很多。当然，在生产环境或者不熟悉的目录里，我不建议开这个，万一它误删文件就麻烦了。
另一种方式是启动后在交互界面里用命令切换权限模式。具体命令可以敲/help查看，不同版本略有差异。
提示：权限给太松有风险，给太紧效率低。我的折中方案是：日常开发目录开完全访问，涉及重要数据时手动确认。
3.3 用自然语言驱动开发的真实体验
Claude Code 最爽的地方是你可以像跟同事说话一样让它干活。比如：
- “把这个文件里的回调改成 async/await。”
- “找出所有没写错误处理的地方，列个清单。”
- “给这个模块补一套单元测试，用 jest。”
它会自己读文件、改代码、跑命令。实测下来，任务描述越具体，结果越靠谱。你说“优化一下代码”，它可能改得面目全非；你说“把这个循环里的重复查询提到循环外”，它就精准得多。
我一般会先让它“只读不改”，输出一个方案，我确认后再让它动手。这样既利用了它的分析能力，又保留了控制权。
3.4 在 VS Code 里配合使用
虽然 Claude Code 是 CLI 工具，但完全可以在 VS Code 的集成终端里跑。打开 VS Code，Ctrl+`` 调出终端，直接敲claude` 就行。这样代码改动会实时反映在编辑器里，看 diff 很方便。
网上有人问“vscode 配置 claude code”怎么弄，其实不需要额外插件，终端里跑起来就够了。如果你想要更深的集成，可以关注一些社区做的 companion 类扩展，但核心还是 CLI 本身。
4. 常见问题与排查技巧实录
4.1 启动类问题速查
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
command not found: claude | npm 全局 bin 不在 PATH | 检查npm config get prefix，加入 PATH |
| 启动后一直转圈 | BASE_URL 不可达 | 检查地址拼写、网络连通性 |
| 鉴权失败 | token 错误或冲突 | 确认只设一个 token，无多余字符 |
| 版本报错 | Node.js 版本过低 | 升级到 18+，推荐 20 LTS |
| 配置文件不生效 | 优先级被覆盖 | 检查项目级.claude目录 |
4.2 那些让人抓狂的细节坑
坑一：token 和 api_key 同时存在。前面提过，这个报错信息很长很唬人，但解决起来就是删一个。我建议统一用ANTHROPIC_AUTH_TOKEN，别混着来。
坑二：Node.js 版本不是越新越好。有人追新装了 v24 的预览版，结果报node.js v24.21.0 is not yet released or is not available。用 LTS 版本，别用尝鲜版，这是血泪教训。
坑三：代理相关配置残留。如果你之前配过一些网络相关的环境变量，可能会干扰 Claude Code 的连接。排查时先把无关变量清掉，保持环境干净。
坑四：项目目录不对。Claude Code 只认当前目录，启动前一定pwd确认一下。我见过有人在 home 目录启动，然后问它“为什么读不到我的项目”，纯属自己坑自己。
4.3 性能与体验优化建议
- 项目别太大：如果目录里有
node_modules这种巨型文件夹，Claude Code 扫描起来会慢。可以在配置里加忽略规则。 - 任务拆小：一次让它干太多事，容易跑偏。拆成小任务，逐个确认，成功率更高。
- 善用只读模式：不确定它会不会乱改时，先让它分析，别直接动手。
- 定期清理会话：长时间不清理，上下文会越来越长，响应变慢。该开新会话就开。
4.4 和其他 CLI 工具的对比感受
市面上类似的 CLI 工具不少，比如 codex cli、zcode cli、trae cli 这些。我用下来的感受是，Claude Code 在“理解项目上下文”和“多文件协同修改”上确实有优势，尤其是让它读整个项目再回答问题的时候，准确率明显高。codex cli 更偏代码生成，trae cli 在特定场景下也不错，但如果你要的是一个能陪你长期做项目的助手，Claude Code 的综合体验更均衡。
当然，工具这东西没有绝对好坏，关键看你的工作流。我的建议是先用 Claude Code 跑通一个完整项目，感受一下它的节奏，再决定要不要引入其他工具。
5. 进阶玩法与长期使用心得
5.1 Skills 与自定义能力扩展
Claude Code 支持 Skills 机制，可以理解为给它装“技能包”。安装方式一般是在配置目录里放对应的 skill 文件，或者通过命令加载。装好之后，它在处理特定任务时会更专业，比如前端组件生成、数据库迁移脚本编写等。
我自己的做法是：把项目里反复出现的任务模式沉淀成 skill，下次直接调用，省去重复描述。这个投入产出比很高，尤其是团队协作时，能把最佳实践固化下来。
5.2 二开与深度定制
有开发能力的朋友可以基于 Claude Code 做二次开发，比如接入自己的内部工具链、定制输出格式、集成到 CI 流程里。它的 CLI 本质是个 Node.js 程序，扩展性不错。不过二开之前建议先把官方文档和源码结构摸清楚，别一上来就改核心逻辑，容易把自己绕进去。
5.3 我踩过的最大一个坑
说个真实经历。有次我在一个重要项目里开了完全访问权限，然后让它“清理一下没用的文件”。结果它把我一个还没提交的配置文件当成“无用文件”给删了。幸好我有 git，git checkout救回来了。从那以后，我定了个规矩：开完全访问权限之前，先确保代码已提交或备份。这个习惯救了我不止一次。
5.4 给新手的三个实在建议
第一，先把 Node.js 版本搞对，这是所有问题的根源。第二，配置只留一个 token，别给自己找麻烦。第三，从小任务开始，别一上来就让它重构整个项目，先建立信任再放权。
Claude Code 这类工具的价值不在于替代你写代码，而在于帮你处理那些重复、琐碎、需要翻来翻去的活儿。把它当成一个不知疲倦的初级搭档，你负责决策和把关，它负责执行和整理，配合起来效率提升非常明显。用顺了之后，你会发现自己有更多时间花在真正需要思考的地方。
