npm安装Claude Code cli

Claude Code 实战指南：在 Windows 上打造你的 AI 编程助手

前言

Anthropic 推出的 Claude Code 是一款命令行 AI 编程助手，能在终端里帮你写代码、查 Bug、重构项目，甚至直接操作文件。本文将从最基础的环境搭建开始，手把手带你完成 Node.js 安装、npm 配置、Claude Code 部署和进阶使用，所有步骤均在 Windows 10/11 上实测通过。

---

目录

1. [为什么选择 CLI 而不是 Web 版](#为什么选择 CLI 而不是 Web 版)
2. [Node.js 详细安装教程](#Node.js 详细安装教程)
3. [npm 快速入门与配置](#npm 快速入门与配置)
4. [安装 Claude Code CLI](#安装 Claude Code CLI)
5. [配置 API Key 的三种方式](#配置 API Key 的三种方式)
6. 基础用法速览
7. [进阶技巧：让 Claude 更懂你的项目](#进阶技巧：让 Claude 更懂你的项目)
8. 配置文件与权限管理
9. 常见问题排查
10. 总结

---

1. 为什么选择 CLI 而不是 Web 版

很多人一开始接触 Claude 都是在浏览器里用 claude.ai。但当你真正需要写代码时，CLI 版本有几个明显优势：

• 上下文感知：CLI 可以直接读取整个项目目录，理解文件之间的引用关系，而不是你必须手动贴代码进去。
• 文件操作能力：CLI 可以创建、修改、删除文件，Web 版只能给你文字回复，你还得自己复制粘贴。
• 自动化流程 ：配合 -p 参数，可以把它嵌入到脚本里，实现自动化的代码审查或文档生成。
• 更低的成本门槛：Web 版需要订阅 Pro，而 CLI 走 API 计费，按量付费，轻度使用更划算。

简单说：Web 版适合聊天和问答，CLI 版才是真正能帮你干活的。

---

2. Node.js 详细安装教程

Claude Code 是一个 npm 命令行工具，而 npm 又依赖 Node.js 运行时。所以一切的前提是先把 Node.js 环境搭好。

2.1 什么是 Node.js

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行时，它让 JavaScript 脱离了浏览器，可以直接在操作系统上运行。对本文而言，你只需要知道：装了 Node.js 就有了 npm，有了 npm 就能装 Claude Code。

2.2 方式一：官网安装包（推荐新手）

这是最简单直接的方式，适合大多数用户。

第一步：下载安装包

打开浏览器访问 https://nodejs.org，你会看到两个下载按钮：

版本类型	说明	推荐场景
LTS（长期支持版）	偶数大版本，稳定性优先，有 30 个月的维护周期	日常开发、生产环境
Current（最新尝鲜版）	奇数大版本，功能最新但可能不稳定	体验新特性、非关键项目

对于我们这种工具链场景，无脑选 LTS 就好。点击 LTS 按钮下载 .msi 格式的 Windows 安装包。

第二步：运行安装向导

双击 .msi 文件，按以下要点逐页操作：

1. Welcome 页：直接点 Next
2. 许可协议：勾选 "I accept..." → Next
3. 安装路径 ：默认是 C:\Program Files\nodejs\，建议保持默认，因为很多工具会到这个路径找 Node.js。如果 C 盘空间紧张，可以改到 D 盘，但要记住你改的位置
4. 自定义安装 ：这里有一个容易漏掉的重要步骤------点击 Add to PATH 旁边的小图标，选择 "Will be installed on local hard drive"（默认是红色 X 表示不安装），确保 Node.js 和 npm 都被加入系统 PATH
5. Native Modules 工具 ：最后一个页面会有一个复选框 "Automatically install the necessary tools..." ，强烈建议勾上。它会在安装结束后自动下载 Chocolatey 包管理器，并用它安装 Python、Visual Studio Build Tools 等编译工具。以后你安装某些包含 C++ 原生模块的 npm 包（如 node-sass、better-sqlite3）时，这些工具是刚需，现在装好一劳永逸

第三步：等待安装完成

点击 Install，等待绿色进度条走完。如果勾选了"自动安装必要工具"，安装完成后会弹出一个 PowerShell 窗口继续下载编译工具链，保持网络通畅让它跑完即可，整个过程可能需要 5-15 分钟。

2.3 方式二：nvm-windows（推荐需要多版本切换的用户）

如果你同时维护多个项目，而不同项目要求的 Node.js 版本不一样（比如老项目用 v14，新项目用 v20），nvm-windows 可以让你随时切换 Node.js 版本。

第一步：安装 nvm-windows

1. 打开 nvm-windows 的 GitHub Releases 页面
2. 下载最新版本的 nvm-setup.exe（或 nvm-setup.zip 解压后运行）
3. 双击安装，一路 Next 即可。注意安装路径不要包含空格和中文字符

第二步：常用 nvm 命令

安装完成后，打开一个新的 PowerShell 窗口（必须是新的），执行以下命令：

# 查看可安装的 Node.js 版本列表
nvm list available

# 安装指定版本（以 20.11.0 LTS 为例）
nvm install 20.11.0

# 使用指定版本
nvm use 20.11.0

# 查看已安装的版本
nvm list

# 查看当前正在使用的版本
nvm current

安装完 Node.js 后，npm 会自动随之安装，不需要额外操作。

提示 ：nvm-windows 和 Node.js 官方安装包只能二选一。如果你之前用官方安装包装过 Node.js，要先在控制面板里卸载干净，再装 nvm-windows，否则会冲突。

2.4 验证安装是否成功

无论你用的是哪种安装方式，最后都应该打开 PowerShell 验证一下：

node --version
# 输出示例：v20.11.0

npm --version
# 输出示例：10.2.4

如果能正确输出版本号，就说明 Node.js 环境已经准备就绪。

2.5 踩坑提醒：旧版本残留问题

如果你电脑上以前装过 Node.js，在装新版之前 建议先去控制面板 → 程序和功能 → 找到 Node.js → 卸载。旧版本残留的全局 npm 包目录（通常在 C:\Users\你的用户名\AppData\Roaming\npm）可能会和新版本的包产生冲突。卸载完成后，手动检查一下这个目录是否存在，存在的话直接删掉。

---

3. npm 快速入门与配置

有了 Node.js 之后，npm（Node Package Manager）就可以用了。下面介绍几个安装 Claude Code 之前必须掌握的 npm 知识。

3.1 npm 是什么

npm 是 Node.js 生态的包管理工具，也是世界上最大的开源软件注册中心。它的核心功能就三个：

1. 安装包：从 npm 远程仓库下载别人发布的代码包
2. 管理依赖：记录项目用了哪些包、什么版本，保证在不同机器上都能复现相同的环境
3. 运行脚本 ：通过 package.json 里的 scripts 字段，定义项目常用的命令（启动、构建、测试等）

3.2 配置国内镜像源（重要）

npm 默认从 https://registry.npmjs.org 下载包，这个服务器在海外，国内直接访问非常慢，甚至经常超时。所以安装完 npm 的第一件事，通常就是切换到国内镜像源。

推荐使用 npmmirror（原淘宝镜像）：

# 设置镜像源
npm config set registry https://registry.npmmirror.com

# 验证是否设置成功
npm config get registry
# 应该输出：https://registry.npmmirror.com

如果你偶尔需要暂时切回官方源（比如发布自己的 npm 包时），可以用 nrm 这个工具来快速切换：

# 全局安装 nrm
npm install -g nrm

# 查看可用源列表
nrm ls

# 切换到 npmmirror
nrm use npmmirror

# 切回官方源
nrm use npm

设置镜像源后并不会马上加速所有包的下载，还需要重启终端让配置生效。

3.3 全局安装 vs 本地安装

npm 安装包有两种模式，理解这个区别很重要：

对比维度	全局安装 npm install -g	本地安装 npm install
安装位置	C:\Users\用户名\AppData\Roaming\npm	当前目录的 node_modules/
使用方式	在任意目录下直接敲命令	只能在当前项目里通过 npx 或 scripts 调用
典型场景	CLI 工具（如 Claude Code、Vite、ESLint）	项目的运行时依赖（如 React、Vue、Axios）
命令示例	npm install -g @anthropic-ai/claude-code	npm install axios

简单记忆法 ：你想在终端里直接敲一个命令就用它 → 全局安装。你想在代码里 import 或 require 它 → 本地安装。

3.4 package.json 是什么

package.json 是每个 Node.js 项目的"身份证"，记录了这个项目的元信息（名称、版本、依赖、脚本等）。它通常位于项目根目录。

快速生成一个 package.json：

# 进入项目目录
cd D:\my-project

# 交互式生成（会问你一系列问题，一路回车就用默认值）
npm init

# 或者跳过提问，直接生成默认的
npm init -y

生成的 package.json 大概长这样：

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

当你在项目里执行 npm install axios 后，这个文件会自动新增 dependencies 字段来记录 axios 的版本号。以后把这个项目复制到另一台电脑上，只需要在项目根目录执行 npm install，npm 就会根据 package.json 里的记录，自动安装所有依赖。

3.5 常用 npm 命令速查

# 初始化项目
npm init -y

# 本地安装一个包（写入 dependencies）
npm install <包名>

# 本地安装一个包（写入 devDependencies，仅开发时用）
npm install <包名> --save-dev

# 全局安装一个包
npm install -g <包名>

# 卸载本地包
npm uninstall <包名>

# 卸载全局包
npm uninstall -g <包名>

# 更新全局包到最新版
npm update -g <包名>

# 查看全局安装了哪些包
npm list -g --depth=0

# 查看当前项目的依赖树
npm list --depth=0

# 清除 npm 缓存（安装异常时常用）
npm cache clean --force

这些命令你现在不需要全记住，用到的时候回来查就行。重要的是理解 -g（全局）和 --save-dev（开发依赖）这两个标志的含义。

---

4. 安装 Claude Code CLI

Node.js 和 npm 就绪后，安装 Claude Code 只需要一条命令。

4.1 全局安装

以管理员身份 打开 PowerShell（右键开始菜单 → Windows PowerShell（管理员）/终端（管理员）），执行：

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

全局安装会将 claude 命令注册到系统中。安装成功后验证：

claude --version

常见报错预警 ：如果你在执行 claude --version 时看到类似下面的错误：

claude : 无法加载文件 C:\Users\xxx\AppData\Roaming\npm\claude.ps1，因为在此系统上禁止运行脚本。

这是 PowerShell 执行策略限制，属于 Windows 的安全机制，不是安装出了问题。请直接跳到本文第 9 节 Q2 查看详细解决办法，两分钟就能搞定。

4.2 后续更新

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

4.3 解决"找不到命令"

如果 PowerShell 提示 claude : 无法将"claude"项识别为 cmdlet...，说明 npm 的全局包目录不在系统 PATH 里。

先用这条命令找到 npm 全局路径：

npm config get prefix

假设输出是 C:\Users\你的用户名\AppData\Roaming\npm，接下来把它加到环境变量里：

1. 按 Win + R，输入 sysdm.cpl，回车
2. 切换到 "高级" 标签 → 点击 "环境变量"
3. 在上方的 "用户变量" 区域，选中 Path → 点击 "编辑"
4. 点击 "新建"，粘贴那个路径
5. 一路确定保存，然后 关掉 PowerShell 重新打开

这是新手最容易卡住的一步。核心原因：改完环境变量后已经打开的终端不会自动刷新，必须重新启动。

---

5. 配置 API Key 的三种方式

Claude Code 需要通过 API Key 访问 Anthropic 的服务。

5.1 获取 API Key

1. 打开 console.anthropic.com
2. 注册 Anthropic 账号（需要海外手机号验证，可以用 SMS-activate 等接码平台）
3. 进入左侧菜单的 API Keys
4. 点击 Create Key ，复制生成的 sk-ant-... 开头的 Key

注意：Key 只在创建时完整显示一次，务必立刻保存。如果丢了只能删掉重建。

5.2 配置方式对比

方式一：临时环境变量（适合偶尔试用）

$env:ANTHROPIC_API_KEY = "sk-ant-xxxxxxxxxxxxxxxx"

只在当前 PowerShell 窗口有效，关掉就没了。

方式二：永久环境变量（推荐日常使用）

用 PowerShell 写入用户级环境变量：

[System.Environment]::SetEnvironmentVariable(
    "ANTHROPIC_API_KEY",
    "sk-ant-xxxxxxxxxxxxxxxx",
    "User"
)

执行后需要重新打开 PowerShell。

方式三：手动设置（不喜欢敲命令就用这个）

同样打开系统环境变量界面（参考第 4.3 节的步骤），在用户变量区域点"新建"，变量名填 ANTHROPIC_API_KEY，变量值填你的 Key。

5.3 验证配置

echo $env:ANTHROPIC_API_KEY

能输出你的 Key 就说明配好了。

---

6. 基础用法速览

6.1 进入交互模式

先 cd 到你的项目目录，然后直接敲 claude：

cd D:\my-project
claude

你会看到一个对话界面，直接打字就能和 Claude 交流。它在启动时会自动扫描当前目录的文件结构，所以可以在对话中引用项目文件。

6.2 一句话模式

用 -p 参数传给 Claude 一个问题，它会直接回答然后退出：

claude -p "用中文解释这个项目的目录结构"

这个模式很适合搭配脚本使用，或者你只想快速问一个问题而不开交互模式。

6.3 引用文件

在对话中用 @文件路径 来引用项目文件，Claude 会自动读取该文件的内容作为上下文：

"审查 @src/utils/request.ts 的代码质量，指出可以优化的地方"

你也可以一次引用多个文件：

"比较 @src/api/user.ts 和 @src/api/order.ts，看它们的错误处理逻辑是否一致"

6.4 实用场景列举

场景	示例指令
代码生成	"在 @src/components/ 下创建一个 Vue3 的弹窗组件"
Bug 修复	"我的程序运行时报 'Cannot read property of undefined'，帮我排查"
代码解释	"用通俗的语言解释 @src/store/index.ts 中这段 Pinia 代码的逻辑"
重构	"把 @src/pages/Login.vue 的 options API 改成 Composition API"
单元测试	"给 @src/utils/format.ts 里的 3 个导出函数写 Jest 测试"

---

7. 进阶技巧：让 Claude 更懂你的项目

7.1 CLAUDE.md 是什么

在项目根目录放一个 CLAUDE.md 文件，Claude 每次启动或对话时都会自动读取它作为"项目说明书"。这比每次手动解释技术栈和规范高效得多。

7.2 怎么写一份有用的 CLAUDE.md

下面是一个实用的模板：

# 项目概述

这是一个基于 Vue 3 + TypeScript 的后台管理系统。

## 技术栈
- Vue 3.4 + Composition API
- TypeScript 5.3
- Pinia 状态管理
- Element Plus 组件库
- Vite 5 构建工具

## 目录约定
- `src/views/` ------ 页面级组件
- `src/components/` ------ 公共组件
- `src/api/` ------ 接口请求模块
- `src/stores/` ------ Pinia store

## 编码规范
- 组件用 `<script setup lang="ts">` 写法
- 文件名用 kebab-case
- API 函数以 `fetch` 为前缀（如 `fetchUserList`）
- 不要使用 `any` 类型

创建方式：

New-Item -Path "CLAUDE.md" -ItemType File -Force
notepad CLAUDE.md

7.3 实用技巧：用 CLAUDE.md 控制 AI 行为

你可以在 CLAUDE.md 里写上对 AI 行为的偏好。比如：

## AI 协作偏好
- 回答问题用中文
- 修改代码前先解释为什么
- 不要自动添加注释
- 优先使用项目已有的工具函数，不要引入新依赖

这样设置后，Claude 在每次会话中都会遵循这些约定，省去大量重复的解释成本。

---

8. 配置文件与权限管理

8.1 配置文件的层级

Claude Code 支持两级配置：

层级	路径	作用范围
全局	C:\Users\你的用户名\.claude\settings.json	所有项目生效
项目级	<项目根目录>\.claude\settings.json	仅当前项目

项目级配置会覆盖全局配置的同名字段。

8.2 常用配置项

{
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "autoApprove": false
}

几个说明：

• model ：默认模型，可选 claude-opus-4-6（最强但贵）、claude-sonnet-4-6（均衡）、claude-haiku-4-5-20251001（最快最便宜）
• theme ：dark / light / system
• autoApprove ：设为 true 后 Claude 修改文件不再需要逐个确认，建议保持 false，尤其是处理重要项目时

8.3 权限模式的三种策略

• 默认模式：修改文件前弹出确认提示，最安全
• 自动批准 ：加 --dangerously-skip-permissions 启动，跳过所有确认------不建议日常使用
• 只读模式：如果你只想让 AI 看代码给建议而不碰文件，目前可以通过在终端里不主动让 Claude 执行写操作来实现，或者直接显式告诉它"只看不改"

---

9. 常见问题排查

Q1：claude 不是内部或外部命令

→ 参考第 4.3 节，检查 PATH 配置，重启终端。

Q2：PowerShell 提示"无法加载文件...因为在此系统上禁止运行脚本"

→ 这是 Windows 平台上最高频的坑，不仅仅是 Claude Code，任何通过 npm 全局安装的 CLI 工具（如 Vite、ESLint、create-react-app 等）都会遇到。完整报错信息长这样：

claude : 无法加载文件 C:\Users\你的用户名\AppData\Roaming\npm\claude.ps1，
因为在此系统上禁止运行脚本。有关详细信息，请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170。
所在位置 行:1 字符: 1
+ claude --version
+ ~~~~~~
    + CategoryInfo          : SecurityError: (:) []，PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

为什么会这样？

Windows PowerShell 默认的执行策略是 Restricted，它的意思是：任何 .ps1 脚本文件都不允许运行 。npm 全局安装的 CLI 工具在 Windows 上会生成一个 .ps1 文件作为启动入口（例如 claude.ps1），当你输入 claude 命令时，PowerShell 实际是在尝试执行这个脚本文件，然后就被执行策略拦下来了。

这本质上是 Windows 的一道安全防线，防止恶意脚本偷偷在你的电脑上运行，而不是你的环境配置有误。

解决方案（3 种方式，推荐第一种）：

方式一：设置 RemoteSigned 策略（推荐）

以管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

系统会提示你确认，输入 Y 然后回车。

这个命令的含义是：

• RemoteSigned：本地编写的脚本可以自由运行，从互联网下载的脚本必须经过数字签名才能运行------既能正常使用 CLI 工具，又保留了对远程不可信脚本的防护
• -Scope CurrentUser：只对当前用户生效，不需要修改整个机器的安全策略

设置完成后，关掉当前 PowerShell 窗口，重新打开一个新的 ，再执行 claude --version 就能正常工作了。

方式二：逐次绕过（不想改策略就用这个）

如果你不想永久修改执行策略，可以每次启动 PowerShell 时临时绕过：

powershell -ExecutionPolicy Bypass

这会以"跳过所有脚本检查"的模式打开一个新的 PowerShell 窗口，在这个窗口里 claude 命令就能正常运行了。缺点是每次都要这样启动，比较麻烦。

方式三：查看当前策略

如果不确定自己当前的执行策略是什么，可以先查一下：

Get-ExecutionPolicy

常见返回值对照：

策略值	含义	npm 全局 CLI 能否运行
Restricted	禁止所有脚本（Windows 默认）	否
RemoteSigned	本地脚本放行，远程脚本需签名	是
AllSigned	所有脚本均需数字签名	否（除非 npm 包有签名，基本没有）
Unrestricted	所有脚本均可运行（不推荐）	是
Bypass	不做任何检查	是

安全提醒 ：不要为了省事把策略设成 Unrestricted。RemoteSigned 是微软官方推荐的最佳实践，在安全性和易用性之间取得了最好的平衡。

Q3：API 返回 401 错误

→ 401 表示认证失败，一般是 Key 没传过去或 Key 无效。最常见的原因：

• 设了环境变量但没重启终端
• Key 复制时多了一个空格
• Key 在控制台被删除或吊销了

先用 echo $env:ANTHROPIC_API_KEY 确认环境变量，再到控制台确认 Key 状态。

Q4：回复很慢

→ 默认使用的是 Opus 模型，能力强但推理慢。可以切换到更快的模型：

在交互模式中输入：

/model claude-haiku-4-5-20251001

或者直接在配置里把 model 改成快模型。日常做代码补全和简单解释，Haiku 的性能完全够用。

Q5：Token 消耗太快，钱包扛不住

→ 几个省钱的习惯：

• 长对话时用 /compact 命令压缩上下文
• 简单问题用 -p 单次模式，不要开交互会话
• 考虑使用 Haiku 模型处理简单任务
• 复杂任务也可以用 /model 临时切模型，不需要的时候再切回来

Q6：npm install -g 报权限错误（EACCES / EPERM）

→ Windows 上常见原因有两个：

• 没开管理员权限 ：全局安装需要写 C:\Program Files\nodejs\ 目录，普通权限不够。以管理员身份打开 PowerShell 再执行
• npm 全局目录权限问题：可以手动把 npm 全局目录改到用户目录下，彻底解决权限问题：

mkdir ~\npm-global
npm config set prefix "$env:USERPROFILE\npm-global"

然后把 ~\npm-global 加入 PATH（参考第 4.3 节的操作），之后全局安装就不需要管理员权限了。

Q7：npm install 下载速度极慢或卡住不动

→ 镜像源没配置或者配置了没生效。先确认：

npm config get registry

如果不是 https://registry.npmmirror.com，回到第 3.2 节重新配置。如果已经配了还是慢，试试清除缓存后重试：

npm cache clean --force
npm install -g @anthropic-ai/claude-code

---

10. 总结

Claude Code CLI 是目前最成熟的 AI 命令行编程工具之一，它的优势在于和项目文件系统的深度集成。整个搭建流程就四步：

1. 装好 Node.js 环境------用官方 LTS 安装包最简单，需要多版本管理就用 nvm-windows
2. 配好 npm 镜像源------切到 npmmirror，省去下载等待时间
3. 全局安装 Claude Code ------npm install -g @anthropic-ai/claude-code 一条命令搞定
4. 写好 CLAUDE.md------让 AI 一次了解你的项目，省去每次解释的成本

相比 Web IDE 类产品，CLI 工具的学习曲线稍高一点，但它更贴近开发者的日常工作流，灵活性也更强------你可以把它放进 package.json 的 scripts 里、整合到 Git hooks 中、甚至写成自动化脚本批量处理代码。建议先从交互模式上手，等熟悉后再逐步探索更高阶的用法。

本文基于 Claude Code 当前版本撰写，如后续版本有界面或配置变化，请以官方文档为准。