Claude Code + Node 从零部署实操：思路、步骤、避坑，一篇讲透

注：常有人把 Claude Code 误打成 “cloud code / clould code”，本文统一用正确拼写。它和上一期讲的 CC Switch 是天生一对——后面会说到。

你听了一堆 “AI 帮你写代码” 的宣传，想上手 Claude Code，又怕环境搞不定。其实把 Claude Code 和 Node 一起讲，逻辑特别简单：Claude Code 本身是个跑在 Node 上的终端智能体，而它要帮你写的也是 Node 项目——所以先把 Node 安对，后面一路顺。

这篇文章把"思路 → 步骤 → 避坑"一次讲清，跟着做半小时能跑通。

---

一、先理清思路：四层模型

把整个链路拆成四层，你就知道每一步在干什么了：

• 运行时层 — Node.js：Claude Code 自己依赖 Node 运行，你的项目也要用 Node 跑。所以它是地基。
• 工具层 — Claude Code CLI：终端里的 AI 编程智能体，能读/写你的代码、跑命令、回答问题。
• 项目层 — 你的 Node 工程：package.json、src/、以及项目级的 CLAUDE.md 指令文件。
• 鉴权层 — Anthropic 账号 / API Key：Claude Code 必须登录才能用，这是最容易卡住新人的一步。

一句话记忆：先有 Node → 再装 Claude Code → 进项目目录开干 → 别忘了登录。

---

二、前置检查：你的 Node 够不够

Claude Code 要求 Node.js 18 及以上（推荐 20 LTS）。先查：

node --version
npm --version

• 如果 node --version 显示 < v18，或者提示 command not found，说明要装/升级，跳到第三步。
• 已经 ≥ 18，直接进第四步装 Claude Code。

---

三、步骤一：安装 / 升级 Node（若缺失）

方式 A：官网装（最省心）
去 nodejs.org 下载 LTS 版本，一路下一步。装完重开终端，再跑 node -v 验证。

方式 B：用 nvm 管理（推荐开发者）

nvm install 20
nvm use 20
node -v      # 应显示 v20.x

nvm 的好处是以后多版本切换不打架。验证 npm：

npm -v       # 应显示 9.x 或更高

---

四、步骤二：安装 Claude Code

官方推荐用 npm 全局安装：

npm install -g @anthropic-ai/claude-code

• macOS / Linux：照上面一行即可。
• Windows 用户：强烈建议在 WSL2 里操作（终端体验最稳）；也可以在 PowerShell 直接用官方脚本：

  irm https://claude.ai/install.ps1 | iex
  

装完立刻验证：

claude --version

能看到版本号，说明装好了。如果报 command not found，多半是 npm 的全局路径没进 PATH，看第九节避坑。

💡 权限报错 EACCES 时不要 sudo npm install -g！正确做法是把 npm 前缀改到用户目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # 或 ~/.bashrc
source ~/.zshrc

---

五、步骤三：鉴权（关键一步）

Claude Code 必须登录。两种常用方式：

方式 A：浏览器交互登录（最常用）
直接在终端运行：

claude

首次启动会弹出浏览器，让你用 Claude.ai 订阅（Pro / Max） 或 Console API 账号 登录，登录完自动写回凭证，关掉浏览器即可。

方式 B：API Key 环境变量（适合 CI / 自动化）

export ANTHROPIC_API_KEY="你的-key"
claude

想永久生效，把 export 那行写进 ~/.zshrc / ~/.bashrc。

两种账号区别：Claude.ai 订阅按套餐；Console API 按 token 计费，适合重度 / 团队。同一邮箱下两者可共存。

---

六、步骤四：初始化 Node 项目并接入

新建一个目录并初始化：

mkdir demo && cd demo
npm init -y

可选地，先放一个入口文件 app.js，比如一个最简单的 HTTP 服务：

const http = require('http');
http.createServer((req, res) => {
  res.end('Hello from Claude Code + Node!');
}).listen(3000, () => console.log('running on :3000'));

然后让 Claude Code 接管这个项目：

claude init     # 生成项目级 CLAUDE.md，写入你的偏好/约定
claude          # 进入交互会话

---

七、步骤五：实战跑通——让 Claude Code 帮你写并跑起来

进入 claude 会话后，直接下指令，比如：

用 Node 写一个返回 JSON 的 HTTP 接口 /api/hello，并帮我启动服务。

Claude Code 会：① 找到/创建 app.js → ② 展示改动并请求你的批准 → ③ 你同意后用 node app.js 跑起来。

验证（另开一个终端）：

curl http://localhost:3000/api/hello
# 应返回 {"hello":"world"}

跑通这一条，你就完成了 “Claude Code + Node” 的闭环：它读你的项目、改你的代码、还能替你执行命令。

---

八、进阶：和 CC Switch 配合（呼应上一篇）

当你手里有 ≥2 套配置（官方账号 / OpenRouter / 国内中转 / 团队号），每次手改 ANTHROPIC_API_KEY、Base URL、重启终端，又烦又易错。这时候用我们上一篇讲的 CC Switch 做配置中枢，在它的图形界面里点一下就能切 Provider，Claude Code 的配置自动写入，不用再翻 JSON。

一句话：Claude Code 负责出力，CC Switch 负责调度。

---

九、避坑清单（收藏这一节）

现象	原因	解决
启动即报 ES module 错	Node 版本过低（<18）	升级 Node 到 20 LTS
EACCES 权限错误	npm 前缀指向系统目录	改 ~/.npm-global，别用 sudo
Windows 下终端乱码/重绘异常	原生 PowerShell 对 ANSI 支持差	用 WSL2 + Windows Terminal
claude: command not found	全局 bin 没进 PATH	把 npm prefix 的 bin/ 加进 shell rc
启动卡在登录	token 过期 / OAuth 变更	删 ~/.claude/.credentials.json 重新登录
切账号麻烦	手动改环境变量	用 CC Switch 一键切换

---

写在最后

Claude Code + Node 的部署，难不在某一步，而在"顺序别乱"：Node 打底 → Claude Code 装上 → 登录 → 进项目。把这张图和第九节的避坑表存好，下次换电脑也能 10 分钟复位。

工具越强，越需要把地基打稳。先把环境跑通，再谈怎么用它放大你的生产力。

---

你装 Claude Code 时卡在哪一步？评论区聊聊，关注我们，持续拆解开发者工具的真实使用门槛。