Claude Code CLI 安装与权限配置全指南：从npm到命令执行

第一次在终端敲下npm install -g @anthropic-ai/claude-code时，我觉得这不就是一次普通 npm 全局安装？结果那条命令卡了十几分钟，报了一串ERR! ERESOLVE overriding peer dependency，装完之后又遇到claude 无法加载、npm.ps1 因为在此系统上禁止运行脚本、CLI 每次都要确认权限……一路拆下来才发现，Claude Code CLI 虽然安装命令只有一行，但真正拦人的从来不是那行命令，而是它前面的 Node 环境、命令分发机制、系统权限策略这些东西。

这篇文章把从npm到claude命令的完整链路拆开讲：先讲三者的依赖关系，再讲安装前环境准备、安装全流程，接着给一份高频报错排查清单，最后是授权和日常使用里最容易踩的权限坑。无论你是第一次装、装完起不来、还是起来后总被权限确认烦到，都能找到对应的处理方式。

1. 从依赖链路看 Claude Code 为什么靠 npm 分发

1.1 Claude Code 本质上是一个 Node.js 包

Claude Code 是 Anthropic 推出的终端编码代理工具，你可以在命令行里直接跟它对话，让它读代码、改文件、跑测试、执行 git 操作。它本质上不是一个编译好的独立二进制，而是一个 Node.js 应用，通过 npm registry 分发，安装方式就是标准的npm install -g。

理解这点很重要，后面一半的报错都源于此：任何影响 Node 环境的东西，都可能影响 Claude Code 的运行。不是 Claude Code 本身写得有问题，而是它的"宿主环境"出了问题。

1.2 官方选 npm 而不是独立安装器，有三个实际考虑

• 跨平台一致：Windows、macOS、Linux 都可以用同一套安装命令，不需要为每个平台做安装包。
• 版本更新链路短：Claude Code 迭代非常快，npm install -g @anthropic-ai/claude-code@latest一条命令就能升到最新，比下载安装包再替换要顺手得多。
• 依赖管理标准化：npm 自带依赖树管理，安装、校验、卸载都走一套成熟机制。

但也正是因为依赖 npm，你的全局 Node 环境一旦被其他项目污染，Claude Code 的安装和运行就会被牵连。后面要讲的 ERESOLVE、EBUSY 就是这么来的。

1.3 安装完成的 claude 命令到底被放到了哪里

npm install -g做的事情很简单：把包下载到全局node_modules，然后在全局 bin 目录生成一个claude命令链接。这个命令是一个 JavaScript 入口文件，系统执行它时通过 shebang 调用 Node 来运行。

所以判断安装是否成功，不止要看 npm 有没有打印added 1 package，还要确认claude是否真的出现在 PATH 能扫到的目录里。

不同系统全局 bin 目录不一样：

系统	全局 bin 目录	验证命令
Windows	%APPDATA%\npm	where claude
macOS/Linux（默认）	/usr/local/bin或/usr/bin	which claude
使用 nvm 时	~/.nvm/versions/node/<版本>/bin	which claude

如果你用了 nvm 管理多个 Node 版本，which claude会显示当前 Node 版本下的路径。一旦切换了 Node 版本，就会报"claude 不是内部或外部命令"，这不是装丢了，而是命令链接跟着旧版本一起"隐形"了。

2. 安装前先把 Node 环境收拾利索

2.1 Node 版本和 npm 版本的底线检查

Claude Code 官方要求 Node 18 以上。我的建议是直接用当前 LTS 版本，比如 Node 22，别用太老的版本，也别非要追最新奇数版本。Node 18 以下装 Claude Code 大概率会在依赖下载阶段失败，而且报错信息不直观，容易让人误判成网络问题。

安装前先跑两条命令确认环境：

node -v npm -v

如果node -v能输出版本号，但npm -v报错，说明 Node 装了但 npm 没进 PATH，或者安装包本身就残缺。遇到这种情况，直接重装 Node LTS 版本是最省事的方案，不推荐手动去拼 npm 路径。

2.2 Windows 高频坑：npm.ps1 禁止运行脚本

很多人在 Windows PowerShell 里执行npm install -g @anthropic-ai/claude-code，结果报：

npm : 无法加载文件 D:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本

这个报错的本质是 PowerShell 执行策略默认限制.ps1脚本运行。npm 本身是一个.ps1包装脚本，PowerShell 出于安全考虑默认不允许执行，于是直接拦下。

解决办法有两种：

第一种是修改当前用户的执行策略，推荐：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

RemoteSigned的含义是：本地创建的脚本可以运行，从网上下载的脚本必须有签名。这样既解决了 npm 的问题，又没有把安全全放开。

第二种是在不需要 PowerShell 特性的场景下直接用 CMD：

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

但这只是绕开问题，不是解决问题，下次跑任何 npm 脚本还会撞上同样的策略限制。建议还是执行第一条，一劳永逸。

2.3 "npm 不是内部或外部命令"的环境变量问题

这个报错和上一个正好相反：命令能找到文件，但系统根本不知道文件在哪。Windows 上常见的原因是安装 Node 时没有把安装目录写进 PATH，或者手动解压了 Node 包却没配置环境变量。

排查路径很简单：

1. 找到npm.cmd所在目录，一般就是 Node 安装目录，比如D:\Program Files\nodejs。
2. 打开系统环境变量，把该目录加到Path中。
3. 重新打开终端，执行npm -v验证。

macOS/Linux 上如果出现npm: command not found，多半是安装方式的问题。用 nvm 安装时注意 nvm 的初始化脚本有没有加载进 shell 配置。

2.4 镜像源：换不换、怎么换

国内网络环境下，直连 npm 官方源安装大包确实慢，甚至超时。很多人第一反应就是切国内镜像。这个操作本身没毛病，但对 Claude Code 要稍微留个心眼。

查看当前镜像源：

npm config get registry

默认应该是https://registry.npmjs.org/。切换国内镜像：

npm config set registry https://registry.npmmirror.com/

切完整包会快很多。但如果你发现切换镜像后安装 Claude Code 时报二进制相关错误，可以临时切回官方源再装一次，因为某些包含原生二进制的依赖在镜像源同步不完整时会出问题。Claude Code 本身是纯 JS 应用，但它的依赖链里有部分包含平台相关二进制的包，所以稳妥起见，装着失败时不排除镜像源的嫌疑。

另外一个排查技巧：npm 安装失败时，先看是不是所有包都慢，还是只有个别包失败。全网都在慢就把镜像源永久切换；只有某个包失败，优先考虑版本冲突，而不是网络。

3. 安装全流程：从装包到验证 claude 命令

3.1 一条安装命令和它的完整输出

环境准备好之后，执行：

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

注意包名是@anthropic-ai/claude-code，不是claude-code，也不是claude。claude是装完之后生成的命令名，不是 npm 包名。这个很多人会搞混，直接npm install -g claude会装到一个完全不相干的第三方包。

所以安装成功不必慌，安装失败也不要看到网上有人成功就直接埋怨网络，先确认你打的包名对不对：

npm view @anthropic-ai/claude-code version

这条命令能直接看到官方包的最新版本号。能输出版本号，说明网络和镜像源都没问题，装不上基本就是依赖冲突或环境问题了。

3.2 权限不足 EACCES 的正规解法

macOS/Linux 上用系统 Node 时，经常遇到：

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

这是因为/usr/local目录默认不属于当前用户。很多人顺手加sudo npm install -g，短期内能用，但后患无穷：sudo 安装的全局包会变成 root 所有，之后升级、卸载都可能再遇到权限问题。

正规做法有两个：

第一个是使用 nvm 管理 Node，这样全局 bin 目录在你的用户目录下，不存在权限问题。

第二个是修改 npm 全局目录前缀：

mkdir -p ~/.npm-global npm config set prefix ~/.npm-global

然后把~/.npm-global/bin加入 PATH。之后所有全局装包都落在这个目录下，不再需要 sudo。

3.3 升级、卸载、强制重装的操作路径

Claude Code 更新频繁，升级很常见：

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

卸载：

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

如果升级后发现行为异常，推荐先卸载再重装。有一个我踩过的坑：升级时 npm 会保留部分旧文件，如果本机之前装过 beta 版，直接升 latest 可能残留旧配置，导致启动时报模块缺失。卸载命令跑完，再手动删掉全局node_modules/@anthropic-ai目录，然后重装，干净利落。

npm 在安装时可能打印这样的警告：

npm warn deprecated node-domexception@1.0.0: use your platform's native DOMException

确实有人看到 deprecated 就不敢用了。其实问题不大。node-domexception是某个依赖包在自己依赖树里带的历史包，因为现在已经有了原生DOMException，所以 npm 提示它已废弃。这个警告一般不会影响 Claude Code 运行，不需要手动干预。记住一个原则：只有ERR!和ERESOLVE级别的东西才需要处理，warn和deprecated只是通知。

验证安装是否真正成功：

claude --version

能输出版本号就是装成功了。如果报"无法将 claude 识别为 cmdlet"或"command not found"，回到第一章的全局 bin 目录去查。

4. 安装和启动中的高频报错，一查一个准

4.1 ERESOLVE overriding peer dependency：依赖冲突的标准处理

安装时报：

npm ERR! ERESOLVE overriding peer dependency npm ERR! While resolving: ...

核心原因是 Claude Code 的某个依赖要求某 peer 依赖版本，而当前 Node 环境里的版本不匹配。这种冲突在全局安装时很常见，尤其当你的全局node_modules里已经装了很多包的时候。

如果你用的 Node 版本符合要求（18+），我推荐先用--legacy-peer-deps装一次：

npm install -g @anthropic-ai/claude-code --legacy-peer-deps

这个参数让 npm 忽略 peer 依赖的严格校验，采用旧版宽松逻辑。对于 Claude Code 这种以"能跑为准"的工具型 CLI，这是有效且副作用较小的路径。

不推荐一上来就--force。--force会强制覆盖冲突，有可能把其他包的依赖关系搞坏，尤其在同一个全局环境里装了很多工具时。

4.2 EBUSY: syscall open：Windows 文件占用问题

报错长这样：

npm ERR! code EBUSY npm ERR! syscall open npm ERR! path D:\...\node_modules\...

Essentially 是 Windows 上文件被进程锁住了。最常见的元凶是编辑器、IDE 或终端进程正在使用相关目录。排查流程：

1. 关闭 VSCode、WebStorm 等编辑器。
2. 关掉当前终端窗口。
3. 重新打开一个干净的终端，执行安装。

如果还不行，可能是杀毒软件或 Windows Search 索引在实时扫描。可以暂时在 npm 配置里关掉对全局目录的实时索引，或者把全局node_modules加入杀软白名单。

清理 npm 缓存也是一个有效步骤：

npm cache verify

4.3 安装成功但 claude 命令消失：nvm 和终端缓存作祟

最诡异的情况是：npm install明明成功，重启终端后claude命令却报"不是内部或外部命令"。这里要区分三种原因：

• 全局 bin 目录没加到 PATH。这个是配置问题，按第二章 PATH 方法解决。
• 用了 nvm，且切换了 Node 版本。全局包跟 Node 版本绑定，切版本后需要重新在当前版本下执行安装。
• Windows 终端缓存：PowerShell 会缓存命令路径，新装命令有时需要重开终端才能识别。

一个实用技巧：装完包不重开终端也能用的话，直接执行：

refreshenv

或者在 PowerShell 里重新加载 profile：

. $PROFILE

这两个命令能刷新环境变量和命令缓存，省去重开终端的麻烦。

4.4 mac 上启动闪退或白屏，先查权限

macOS 上有些用户会反馈：claude运行后界面一闪而过，或者点回车没反应。这种现象不少跟 macOS 的权限弹窗有关。系统默认不信任终端对某些目录的访问，权限弹窗被忽略后，Claude Code 想读文件又读不到，表现就是"看似启动了但用不了"。

下一步直接看系统设置里的"隐私与安全性"，把当前使用的终端模拟器（或者 VSCode）相关权限打开，尤其是文件访问和辅助功能权限。

5. 首次启动、登录授权与权限管理

5.1 登录验证的方式和选择

安装完成后，在终端执行：

claude

首次使用会提示你登录 Anthropic 账号，通常会自动打开浏览器完成授权。如果终端环境不支持自动跳转，也可以手动前往授权页输入 code。

需要说明的是，Claude Code 需要可用的 Anthropic 账号，登录成功后才能正常调用模型能力。登录状态存在本地用户目录下，不需要每次都重新登录。如果遇到登录失效，执行：

claude /logout

然后重新/login即可。

5.2 "完全访问权限"到底指什么

很多搜索词里都在问"Claude Code CLI 如何给完全访问权限"，这个说法其实对应两种场景：

macOS 场景：系统设置里"隐私与安全性"中的"完全磁盘访问权限"。Claude Code 在读写终端所拥有的文件权限时，如果 macOS 限制了终端对某些目录的访问，就会失败。处理方式是把你的终端应用加入完全磁盘访问权限列表，并确保"辅助功能"权限也已授权。

Claude Code 内部场景：Claude Code 默认会在执行文件操作、命令前逐条询问用户确认，需要用户授予"访问权"才能继续。这个在 CLI 里体现为每次任务前的一次次Allow?弹窗。

这两类"权限"不是一回事。完全磁盘访问权限属于操作系统层面，Claude Code 的/permissions属于应用权限模型。搞清楚这个区别，你才不会被网上的混乱教程带偏。

5.3 避开每次确认：从 allowlist 到 permission mode

Claude Code 默认的安全策略是谨慎的：每次要读写文件或执行命令前都会问你是否允许。频繁确认确实破坏体验。官方设计了几种减少确认的方式：

1. 使用 allowlist。在设置文件中指定自动允许的操作，比如：

{ "permissions": { "allow": [ "Read(~/repo/**)", "Write(~/repo/**)", "Run(npm run build)" ] } }

这样匹配到的操作不会弹确认，未匹配到的仍然询问。这是我最推荐的方案，兼顾安全与效率。

2. 使用 permission 模式。启动时指定：

claude --permission-mode acceptEdits

这个模式会自动接受文件编辑请求，但命令执行仍会询问。

3. 完全跳过确认：

claude --dangerously-skip-permissions

这个参数的名字已经说得很明白了：极度危险。它会跳过所有权限确认，等于你授权 Claude Code 无所顾忌地改文件、执行命令。我只建议在一次性容器、沙箱、CI 临时环境里使用，日常开发不要开着它干活，否则一个错误的命令可能直接破坏你的代码库。

5.4 配置目录和二次开发方向

Claude Code 的配置和管理文件集中在用户目录下的.claude目录中。安装 skills 时，把 skill 文件夹放进这个目录对应的 skills 目录，就能在会话里被加载。这也是目前社区里讨论比较多的"Claude Code 二次开发"方向之一：通过 skills 给 Claude Code 注入自定义技能。

如果你对扩展开发感兴趣，可以先从官方 docs 里的 settings 和 skills 配置开始，不需要写插件，就把工作目录里的约定和指令通过 CLAUDE.md 喂给它，效果立竿见影。真正需要写代码的二次开发，通常是给 Claude Code 对接公司内部工具链，这部分等你能流畅使用基础功能后再碰也不迟。

6. 融入日常开发环境：VSCode 集成和项目级配置

6.1 在 VSCode 里跑 Claude Code

Claude Code 可以直接在 VSCode 的终端里跑，也可以安装官方扩展获得更顺滑的体验。扩展装好后，通过快捷键Ctrl+Shift+P打开命令面板，输入 Claude 相关命令就能启动会话。

在 VSCode 里使用的好处是：Claude Code 能感知编辑器打开的项目结构，你可以在侧边栏或终端里同时查看它生成的变更，代码比对和回滚都比纯终端场景顺手。

需要注意的一点，VSCode 集成时，系统权限弹窗可能指向的是 VSCode 这个应用而不是终端。如果你发现 Claude Code 在 VSCode 里无法读写文件，去系统设置里检查 VSCode 是否被授予了文件夹访问权限。

6.2 项目级 CLAUDE.md：给 Claude Code 交底

进入项目目录首次运行claude时，可以在会话里执行：

/init

Claude Code 会扫描项目结构，自动生成一个 CLAUDE.md 文件。这个文件相当于项目的"使用说明书"，里面可以写清：

• 项目的启动命令和构建命令
• 代码风格和目录结构约定
• 禁止修改的目录（比如 node_modules、dist）
• 测试命令和 lint 规范

Claude Code 每次启动会话时都会自动读取项目里的 CLAUDE.md。你花十分钟写一份高质量的说明，后面每次交互都能节省大量时间。

6.3 常用命令速查

日常用得最多的几个命令，整理成表方便查阅：

命令	作用
claude	进入交互式会话
claude "重构这个模块"	直接执行一次性任务
claude -c	继续最近一次会话
claude --model claude-sonnet-4-5	指定模型
/status	查看当前进程和 token 消耗
/init	生成 CLAUDE.md
/logout	退出登录
/permissions	查看和管理权限配置

把claude当成你项目的常驻助手，而不是偶尔想起来才跑的玩具。配合 npm 项目里的npm run dev、npm run build命令，你甚至可以把它接进验证循环里：改完代码让它自动跑构建、跑测试、把报错信息反馈回来。

我个人实际操作中的体会是：大部分所谓"Claude Code 安装失败"的求助帖，最后都落回两个原因，一个是包名打错，另一个是 Node 环境多年没收拾。只要理解npm install -g只是在做"解压一个 Node 包 + 建立一个 bin 链接"，就能按照本文的链路一步步自查。先确认 Node 版本、再确认 PATH、再确认镜像源，最后才考虑依赖冲突和系统权限，这套顺序永远不会错。最后一个建议：日常使用不要开--dangerously-skip-permissions，把Read、Write的 allowlist 写清楚，这件事值得花半小时做好。