前阵子公司一台内网 Linux 服务器需要部署 claude code机器权限倒是齐全唯一的麻烦是完全没有外网。更尴尬的是这台机器连 Node.js 环境都没有npm 自然也不存在。折腾了整整一个下午从下载 Node.js 安装包开始到把 claude code 装上期间踩了一堆 npm 离线安装相关的坑。回头复盘这件事真正有价值的经验其实不是“怎么装 claude code”而是“npm 离线安装软件包”的完整方法论——内网部署任何 npm 包无论是自研工具还是第三方 CLI这套流程都能复用。claude code 是 Anthropic 针对开发者推出的 AI 编程助手通过 npm 全局安装后在终端里以claude命令运行常见的安装命令就是npm install -g anthropic-ai/claude-code。如果你在能联网的开发机上执行这条命令几十秒就完事但在隔离网络环境里事情就变成了一道不折不扣的供应链题目依赖从哪来、怎么传进内网、以什么形态落地。这篇文章会把离线安装的三种主流思路、完整实操命令和内网环境最常见的问题一次性讲透。1. 为什么需要离线安装场景与思路1.1 离线安装的典型场景说到离线安装很多人第一反应是“局域网服务器装软件”。但实际上我做过的离线安装需求来自好几个方向彼此的关注点还不一样生产环境隔离网不少企业内部的生产网段和互联网物理隔离所有软件必须走审批、走介质传递。这种环境经常连操作系统补丁都要手动导入npm 包自然不可能现场下载。云上专有网络云服务器虽然能挂公网 IP但出于安全策略会关闭出站流量或者只开放特定端口。我遇到过一次云主机只能访问内网服务npm registry 地址根本无法连通。外网不稳定的机房有些海外节点访问 npm 主站奇慢无比安装一个中型项目能等半个小时中间还经常 EAI_AGAIN 报错。这时候如果能把依赖在本地打好包再带过去效率完全不一样。离线教学或竞赛环境需要给一台没有网络的电脑准备一套可用的 Node 开发环境常见于培训教室、比赛现场。这些场景都有一个共同点目标机器本身具备完整的本地运行能力唯一缺的是“下载”这个动作。所以离线安装的本质就是把“网络下载”这个环节提前在一台能联网的机器上完成再把下载结果整体搬运过去。1.2 三条核心思路缓存、打包、整拷npm 离线安装不是只有一条路按照依赖组织的粒度可以分为三档方案核心原理优点缺点npm cache 离线缓存利用 npm 的本地缓存目录把安装过的包完整缓存后再迁移覆盖完整依赖树幂等可靠最推荐缓存目录体积偏大npm pack 手动打包用npm pack把指定包打成 tgz 再手动管理精细可控适合单包分发不自动收集依赖复杂包会漏依赖node_modules 整体搬运把联网机器上的安装产物整个复制到目标机最简单粗暴省去在目标机上的安装过程原生模块跨平台失效路径硬编码风险这里先记住一个结论能走 cache 方案就别走 pack 方案能用 pack 方案就别整拷 node_modules。原因在后面核心实操里你会彻底明白——前两种虽然也需要理解 npm 的工作机制但至少依赖关系是清晰的而整拷属于风险最高的“暴力迁移”只适合作应急纪律。你还需要知道一个 npm 的关键特性npm 的下载本质上是“先入缓存再解压到 node_modules”。也就是说只要你在联网机器上成功安装过某个包这个包及其所有依赖就已经躺在本机缓存里了。离线安装要做的就是把这份缓存当成移动硬盘来用。这个认知是整个离线思路的基础后面所有方案都围绕它展开。2. 离线安装前的准备环境与判断2.1 检查 Node.js 环境与 npm 版本开始离线安装之前先给目标机器做一次环境体检。命令就三条node -v npm -v which node这里有个很容易忽略的坑claude code 对 Node.js 版本有最低要求。根据官方说明它要求 Node.js 18 以上的版本我测试时用 20.x 和 22.x 都没问题。如果你的内网机器只有 Node 16直接装会报 engine 不匹配的警告有些依赖甚至会直接安装失败。所以离线安装的第一步其实是确保目标机器上有一个足够新的 Node.js 运行时。如果 Node 也没有还得单独准备 Node 安装包——官方提供了.tar.xz免编译压缩包解压后把bin目录加进 PATH 就能用很多内网环境我是直接这样干的比 rpm/deb 省事。npm 版本也会影响离线行为的细节。新版 npm9.x、10.x对各种安装模式的支持更完善比较重要的是--offline和--prefer-offline这两个参数能否正常工作。建议内网机器统一使用 npm 10和当前主流 Node 20 配套兼容性最好。2.2 理清 npm 的缓存目录与配置npm 的缓存目录默认位于用户根目录下的.npmLinux/macOS 是~/.npmWindows 是%LocalAppData%\npm-cache。你可以随时用一条命令确认npm config get cache缓存目录内部结构主要是_cacache文件夹里面的内容是内容寻址存储以哈希值为键保存数据。这就是离线迁移的核心资产。需要特别注意npm 的缓存不是简单的“下载目录”它会包含包的 metadata 和 tarball 的完整记录因此只要缓存完整npm 就能在完全离线的情况下完成版本解析和文件解压。还有两个配置值得提前看npm config list npm config get registrynpm config list会展示全局和用户的全部配置registry一眼就能看出来源地址。在联网机器上准备离线包时如果你的网络访问默认 npm 源很慢可以先设置一个国内镜像源比如https://registry.npmmirror.com把环境变量或.npmrc里的 registry 指过去速度会快很多。但这里有个关键细节一旦你用了自定义 registry 下载包缓存里的 key 会绑定这个 registry 地址。迁移到内网后内网机器的 npm 也应当配置相同的 registry 来源否则离线安装时可能出现缓存无法命中——这一点我在第 4 节会再强调。2.3 判断该走哪条路一张决策清单工具选型不能靠拍脑袋我总结了一份判断流程按顺序回答几个问题就清楚该用哪种方案联网机器和目标机器的操作系统、CPU 架构是否一致答案是否则优先放弃 node_modules 整拷。要安装的是带有很多依赖的大型应用还是一个相对独立的 CLI 工具前者优先 cache 方案后者可以用 pack 方案。目标机器上是否已经存在部分依赖如果存在pack 方案的漏依赖问题影响会小一些。内网是否允许通过审批或介质传递较大体积的文件cache 方案动辄几百 MB如果介质空间紧张pack 方案更轻。以 claude code 为例它本身是一个 AI 编程助手的 npm 包完整依赖树的体积并不算夸张我实际测下来整个缓存目录只有几十 MB 到一百多 MB。这个量级走 cache 方案完全没问题。如果你的内网介质只能拷贝单个小文件那就考虑 pack 方案但要接受依赖收集的繁琐。3. 核心实操离线打包与安装 claude code3.1 方案 Anpm cache 离线缓存迁移推荐这是我最推荐、也是实测最稳的方案。它利用了 npm 安装时“先把 tarball 写进缓存再从缓存解压安装”的机制把整个缓存目录搬到内网后用--offline参数强制 npm 不从网络获取任何信息。第一步在联网机器上准备离线缓存找一台能访问外网的 Linux 或 Windows 机器执行全局安装同时手动指定缓存目录这样缓存文件会集中在一个文件夹里方便整个打包带走mkdir -p /tmp/cc-offline/cache cd /tmp/cc-offline npm init -y npm install anthropic-ai/claude-code --cache /tmp/cc-offline/cache执行完以后/tmp/cc-offline下会有一个 node_modules 目录和一个 cache 目录。这里有个细节如果你只执行npm install默认的缓存目录是用户目录所以必须像上面这样手动指定--cache到一个统一目录否则拷贝缓存时会漏文件。另一个方式是把安装产生的整个cache目录使用tar打包tar -czf cc-cache.tar.gz /tmp/cc-offline/cache打包时不要把绝对路径也打进去因为目标机器的解压目录可能不同。我习惯在/tmp/cc-offline内相对路径执行压缩。第二步把缓存迁到内网机器介质拷贝的方式可以是 U 盘、内部传输系统或者堡垒机上传。关键是从这一步开始内网机器必须“只靠本地文件工作”。拷贝完成后解压mkdir -p /opt/cc-offline/cache tar -xzf cc-cache.tar.gz -C /这会把缓存文件还原到/tmp/cc-offline/cache。如果你希望放到更整洁的路径可以解压后把内容挪到/opt/cc-offline/cache并保证目录结构不需要改变。第三步在内网机器上离线安装现在回到目标机器执行离线安装cd /opt/cc-offline npm install anthropic-ai/claude-code --offline --cache /opt/cc-offline/cache--offline参数是关键它让 npm 只从缓存读取数据不会发任何网络请求。验证安装结果claude --version看到版本号输出就说明 claude code 已经成功装上。如果执行命令时报“command not found”通常是全局安装路径没有加入 PATH或者安装的是局部目录这个在第 4 节我会给出排查方法。有一点提醒一下npm install如果在根目录没有package.json时会报错所以我习惯在/tmp/cc-offline先执行npm init -y。但在目标机器上执行离线安装时不需要保留联网机器上的 package.json进入一个空目录直接安装也可以npm 会把包装进当前的 node_modules 目录。如果你希望把 claude code 作为全局命令使用加上-g参数npm install -g anthropic-ai/claude-code --offline --cache /opt/cc-offline/cache实测全局安装和局部安装在这个流程里都可以成功唯一的差异是命令在 PATH 里的位置。3.2 方案 Bnpm pack 手动打包npm pack的思路是把单个 npm 包打包成一个.tgz文件传进内网后用npm install /path/to/package.tgz安装。它适合依赖树非常浅的包或者目标机器上已经有大部分运行时依赖的场景。在联网机器上执行npm pack anthropic-ai/claude-codelatest执行后会生成一个类似anthropic-ai-claude-code-1.x.x.tgz的文件。这个名字的规律是包名中的换成-/换成-后面跟版本号。把这个文件传到内网机器后执行npm install ./anthropic-ai-claude-code-1.x.x.tgz这个方案最大的坑是依赖不会被自动收集。npm pack只打包目标包自身不会递归下载它的 dependencies。如果 claude code 依赖了别的运行时库而这些库在内网机器上不存在安装时会直接报错你就得一个个去手动 pack 那些依赖。遇到这种情况我一般先看node_modules/anthropic-ai/claude-code/package.json里的dependencies字段把里面列出的包全部 mark 下来逐个npm pack再写一个批量安装命令。不过实测下来claude code 的依赖树并不算深核心依赖主要集中在几个 AI SDK 相关的包上。加上它本身有平台相关的二进制包依赖完整收集会比较痛苦。所以这个方案只作为“最小场景”参考遇到多依赖包请直接回到方案 A。3.3 方案 Cnode_modules 整体搬运应急方案 C 的精髓是“安装产物即安装结果”——在联网机器上装好 claude code 之后直接把整个 node_modules 目录拷到目标机器。这在架构一致的 Linux 机器之间通常能跑起来前提是目标机器上已经有完全一致的 Node.js 版本。移植以后建议立刻执行一次npm rebuildnpm rebuild会尝试重新编译原生模块。但问题来了如果原生模块在编译阶段需要联网下载工具链离线环境下照样失败。这就是我说整拷只适合应急的原因——除非你确定这个包的依赖全部是纯 JavaScript否则跨机器迁移后随时可能冒出一个.node二进制文件加载不了。对于 claude code最安全的应急方式是只拷贝它的全局安装目录而不是项目 node_modules。全局 CLI 的安装位置可以用npm prefix -g查出来。把该目录压缩包到目标机器解压到相同位置再把目录中的binWindows 叫cmd或同名.ps1放入 PATH。这样 claude code 可以正常启动省去重新安装的步骤。但要注意全局目录里可能还有别的 npm 全局包最好先列一下再打包npm ls -g --depth03.4 三步实操背后的核心追问为什么是 cache 而不是复制 node_modules聊到这里有个问题值得认真回答既然npm install之后 node_modules 已经是一份完整可运行的产物为什么更推荐先迁移 cache 而不是直接拷 node_modules原因有三点。第一cache 是 npm 官方识别的“安装源”迁移 cache 后内网机器执行的标准npm install会自动从 cache 补齐依赖树而手工复制 node_modules 并不会更新任何 npm 内部记录如果后续要装新包npm 的解析结果会和现场 node_modules 不一致。第二不同操作系统和 CPU 架构的差异。cache 里保存的是平台无关的 tarball目标机器安装时会解压成适合本平台的产物。node_modules 则已经完成了解压和编译夹带着源机器的原生二进制。我踩过最典型的坑就是 Linux x64 上打包的的包跑到 ARM 机器上运行时直接抛“invalid ELF header”。用 cache 方案在目标机器上重新安装就不会有这个问题。第三可重复性。cache 目录是幂等的——同一份 cache 可以在多台内网机器上反复使用每次安装结果一致。而手工复制 node_modules 如果在传输途中丢失任一文件排错过程会非常痛苦。所以我的结论很简单离线安装的稳定路径 缓存迁移 目标机器原生安装。4. 常见问题与排查实录4.1 npm.ps1 执行策略报错Windows 特有Windows 环境下的离线安装有一个高频问题执行npm install时直接报npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这个问题的根源不是 npm 本身坏了而是 PowerShell 的执行策略默认限制运行.ps1脚本。npm 的 Windows 入口实际是两个文件npm.cmd给 CMD 用和npm.ps1给 PowerShell 用。在 PowerShell 里调用 npm 时系统检查执行策略并拒绝运行这个脚本。解决方案是放宽当前用户的执行策略在 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser之后重新打开终端即可。这个修改只影响当前用户不涉及系统级安全策略内网机器可以放心执行。如果你只想用 CMD 绕过也可以直接打开“命令提示符”而不是 PowerShellnpm.cmd 不会触发这条限制。这个方法对离线安装场景同样有效因为问题只出在命令入口不涉及网络。4.2 “npm 不是内部或外部命令”与 PATH 问题很多内网服务器装完 Node.js 后执行node -v正常但执行claude却提示命令找不到。这类问题的本质是 PATH 里没有全局安装目录。先确认 npm 全局 prefixnpm prefix -gLinux 默认是/usr/local全局 bin 在/usr/local/bin如果你自己解压的 Node 放在/opt/node那么 bin 在/opt/node/bin。把它加入 PATHexport PATH/opt/node/bin:$PATH建议把这段写入/etc/profile.d/node.sh让所有用户登录时自动生效。Windows 上则要把C:\Program Files\nodejs和%AppData%\npm都加进系统环境变量 Path——热搜里那条“npm 不是 cmdlet 或可运行程序”的报错十有八九就是这两个目录缺失导致的。4.3 ERESOLVE 依赖冲突错误内网安装时执行npm install有时会看到npm warn ERESOLVE overriding peer dependency或者直接 error 退出。这个问题的来源是新版 npm 采用了更严格的对等依赖解析逻辑当某个包声明的 peer 依赖和现有的依赖树不兼容时npm 默认不会强行安装。离线环境下你没法临时升级依赖来满足解析所以最实用的处理方式是在安装命令里放宽规则npm install --legacy-peer-deps --offline --cache /opt/cc-offline/cache--legacy-peer-deps使用旧版 npm 的依赖解析方式跳过对等依赖冲突检查。这个参数在离线场景特别有用因为即便在联网环境中处理 peer 冲突时你也可以临时改一下 package.json 里的版本约束但离线时没法快速验证加这个参数是最快的路径。注意它只影响安装行为不影响运行时正确性。4.4 离线安装完成后 claude 命令报错装好之后执行claude --version出现Error: Cannot find module之类的问题常见的三个原因全局安装与局部安装混淆claude命令实际被安装到了局部 node_modules/.bin但没有被 npm 全局链接。解决方法是重新执行npm install -g。Node 版本不满足要求claude code 要求 Node 18低版本运行时加载某些语法会直接报错。执行node -v确认版本。缓存条目损坏打包压缩再解压的过程中如果缓存文件的校验值不匹配npm 会读取失败。这种情况我建议在联网机器上重新做一次完整的 cache 迁移拷贝时使用tar -czf而不是简单的cp -r因为 tar 会保留文件权限和符号链接这对缓存目录很重要。4.5 缓存内网迁移后的 registry 不一致问题这是离线安装最隐蔽的坑。如果你在联网机器上用了自定义镜像源下载包那么缓存里的包记录会带上该源的 URL 作为 key。内网机器的 npm 默认 registry 是官方源地址执行npm install --offline时npm 会尝试根据 key 来匹配缓存条目一旦 registry 不匹配即使缓存文件就在本地也无法命中。我踩过一次之后总结了一个最简单的规避方式在联网机器上准备离线缓存时先统一把 registry 设置成内网将要使用的地址。例如内网机器希望用官方源联网机器也保持默认如果内网准备搭建本地 npm 私服那么联网机器下载时就把 registry 指向私服地址npm config set registry http://your-internal-registry/这种方式不仅解决 key 匹配问题还让内网机器可以直接用私服做增量安装。如果你只是临时做一次离线迁移没有后续增量需求那么只需保证两台机器的registry配置字符串完全一致即可。5. 个人实操体会与避坑清单离线安装做多了之后我的经验总结成一句不要把“能装上”当成目标要把“整套依赖供应链可复制”当成目标。这意味着你在联网机器上做准备的每一步都要想清楚——这份缓存以后要在什么样的机器上、用什么样的 npm 版本、以什么样的 registry 配置来消费。否则你只是把问题从“装不上”变成了“换台机器又装不上”。最后分享一个小技巧我在内网批量部署 npm 包时经常用。联网机器上准备完 cache 之后写一个很简单的部署脚本跟着 cache 一起带进内网#!/bin/bash set -e CACHE_DIR/opt/cc-offline/cache mkdir -p $CACHE_DIR tar -xzf cc-cache.tar.gz -C $CACHE_DIR npm install -g anthropic-ai/claude-code --offline --cache $CACHE_DIR claude --version这样一个 tar 文件加一个脚本整个安装过程从人工操作变成半自动化后面再遇到其他机器要装 claude code直接把这两样东西丢过去两三分钟就跑完既不会漏步骤也方便给没有 npm 离线经验的同时照着执行。内网环境里“可编排、可重复”比“一次成功”重要得多。
