1. 为什么需要离线安装
在企业开发环境中，开发机往往处于严格的内网隔离状态，无法直接访问公网。本文将从这一实际痛点出发，介绍为什么标准的 npm install 或在线安装工具在安全可控的环境中会失效，以及离线安装方案的现实意义。具体来说，以下场景在实际工作中十分常见：
- 依赖拉取失败导致构建中断：开发团队在内网 CI/CD 流水线中执行
npm install时，由于无法连接公共 npm registry，大量第三方包下载超时或直接报错，导致整个构建流程卡死，严重影响迭代效率。 - 安全审计与合规要求：金融、政务等强监管行业要求所有引入的依赖包必须经过安全扫描和审批，禁止开发机直接访问外网下载未经审计的代码，离线安装配合私服成为满足合规的必要手段。
- 网络带宽与稳定性限制：大型团队同时从公网拉取依赖时，出口带宽极易被打满，不仅拖慢下载速度，还可能触发公司网络限流策略；离线缓存方案可以一次下载、多次分发，显著降低带宽压力。
2. Claude Code 的包结构分析
在动手制作离线安装包之前，必须先搞清楚 Claude Code 的 npm 包到底长什么样、依赖了哪些东西。解压官方 .tgz 包后，核心目录和文件大致如下：
package.json：声明了包名、版本、主入口文件以及所有dependencies。这是后续梳理离线缓存的起点。cli.js或index.js：CLI 主入口文件，负责解析命令行参数、加载内部模块并启动交互式会话。vendor/或assets/：可能包含与 AI 引擎交互所需的静态资源、配置文件或预置的 prompt 模板。node_modules/（发布包中通常不直接包含，而是由package.json声明后由 npm 自动安装）：这是离线安装中需要重点处理的部分——必须提前将这部分依赖解析并缓存好。
理解这套目录结构后，下一步就是系统性梳理整个依赖树，明确哪些包可以在内网复用、哪些必须提前从外网拉取并打入离线包。
3. 关键依赖梳理与缓存策略
Claude Code 作为一个与 AI 服务深度交互的终端工具，其依赖树往往比普通 npm 包更复杂。以下三类依赖需要重点关注：
- 核心运行时依赖：如 Node.js 内置模块的替代封装、终端交互库（例如
inquirer、chalk）、网络请求库以及加密模块。这类包通常数量不多，但版本要求严格，建议提前锁定并打入离线包。 - AI SDK 与协议层依赖：Claude Code 底层会依赖 Anthropic 官方 SDK 或其 HTTP/WS 客户端封装。这类包的子依赖链较长，需要递归解析，确保离线环境下的调用路径不会因缺少中间层而报错。
- 平台特定二进制文件：某些 native addon 可能依赖系统级的
.node文件或动态链接库。如果离线目标机器与打包机器的操作系统或 Node.js 版本不同，需要特别注意 ABI 兼容性。
缓存策略上，推荐采用 全局缓存 + tarball 归档 的混合方案：
- 在一台可连接外网的构建机上，执行
npm install --legacy-peer-deps完整安装整个依赖树。 - 使用
npm pack <package-name>或直接从 npm 缓存目录~/.npm/_cacache中提取所有依赖的.tgz文件。 - 将提取出的 tarball 文件按包名分类存放，打包成离线依赖包归档文件（如
claude-code-offline-deps.tar.gz），后续在离线环境中直接通过npm install <tarball>的方式还原依赖，完全绕开对公网 registry 的访问。
4. 离线安装全流程实战
以下是一套经过验证的端到端离线安装流程，假设目标环境是 Linux 内网机器，Node.js 18+ 已预装。
第一步：在外网构建机上准备离线包
# 1. 创建临时工作目录
mkdir ~/claude-code-offline && cd ~/claude-code-offline
2. 安装 Claude Code（这里以 @anthropic/claude-code 为例，实际包名以官方为准）
npm pack @anthropic/claude-code
生成 claude-code-x.y.z.tgz
3. 解压并安装完整依赖
tar -xzf claude-code-x.y.z.tgz
cd package
npm install --legacy-peer-deps
4. 把所有依赖打包成离线依赖包
cd node_modules
for pkg in *; do
npm pack "$pkg" 2>/dev/null || true
done
mkdir ~/claude-code-offline/tarballs
mv *.tgz ~/claude-code-offline/tarballs/
5. 同时保留 Claude Code 自身包和 node_modules 中的 .bin 目录
cd ~/claude-code-offline
cp package/claude-code-x.y.z.tgz .
第二步：将离线包传输到内网机器
使用 U 盘、内网文件共享或堡垒机安全传输通道，将 ~/claude-code-offline 目录整体拷贝到目标机器。务必保证 tarballs/ 子目录下的所有 .tgz 文件完整无缺。
第三步：在目标机器上执行离线安装
# 1. 创建项目目录
mkdir ~/my-project && cd ~/my-project
2. 安装 Claude Code 自身包
npm install /path/to/offline-pack/claude-code-x.y.z.tgz
3. 安装所有离线依赖
cd node_modules/.package-lock.json # 或直接使用批量安装脚本
for tgz in /path/to/offline-pack/tarballs/*.tgz; do
npm install "$tgz" --save
done
如果依赖较多，更推荐用 npm install 的 --offline 模式配合预先缓存好的 registry 目录
完成以上步骤后，Claude Code 的 CLI 命令即可在离线环境中正常使用，整个安装过程不会触发任何外网请求。
5. NPM 私服与代理方案
对于长期维护的团队来说，每次手动打包传输 .tgz 文件既繁琐又容易出错。更成熟的方案是搭建内网 NPM 私服，让离线环境也能像访问公网 registry 一样流畅地安装依赖。以下推荐两种主流方案：
5.1 使用 Verdaccio 搭建轻量私服
Verdaccio 是一个零配置的轻量级 npm 私服，非常适合中小团队快速搭建离线缓存代理。部署步骤极为简单：
# 在能访问外网的跳板机上安装 Verdaccio
npm install -g verdaccio
启动 Verdaccio（默认监听 4873 端口）
verdaccio
配置 npm 源指向私服
npm set registry http://localhost:4873/
Verdaccio 自带 上行链路（uplink） 功能：当内网请求某个包时，它会先检查本地缓存，命中则直接返回；未命中则代理到公网 npm registry 下载并自动缓存。这意味着团队只需在跳板机上运行一次 npm install，所有依赖就会沉淀到 Verdaccio 的存储目录中。之后将整个存储目录迁移到内网机器，内网开发人员无需任何外网访问即可正常安装。
5.2 使用 Nexus / JFrog Artifactory
如果团队已经有统一的制品仓库（如 Nexus Repository 或 JFrog Artifactory），可以直接开启 npm 代理仓库功能。这类企业级方案的优势在于：
- 权限与审批流：可以对接 LDAP/AD，按团队或项目控制包的访问和发布权限。
- 安全扫描集成：自动对缓存下来的依赖包进行漏洞扫描，满足合规要求。
- 多仓库聚合：将 npm、Docker、Maven 等不同技术栈的制品统一管理。
配置本质上与 Verdaccio 类似：在外网区域部署代理仓库并完成首次全量拉取，然后将仓库数据目录同步到内网对应的只读实例中。
方案选型建议：团队规模小于 20 人、没有现成制品仓库时，Verdaccio 足够好用；大型企业或已有 Nexus/Artifactory 基础设施的团队，优先复用现有平台。
6. 离线安装后的验证与排错
完成离线安装后，不能想当然地认为一切正常。以下验证步骤和常见问题排查清单可以帮助你快速确认 Claude Code 是否真正可用。
6.1 基础验证
- 检查 CLI 是否可执行：在终端输入
claude --version（或官方指定的启动命令），确认能正确输出版本号而非command not found。 - 验证依赖完整性：进入项目目录，执行
node -e "require('@anthropic/claude-code')"（以实际入口包名为准）。如果报MODULE_NOT_FOUND，说明仍有依赖缺失，需要回到步骤 3 中补充对应的 tarball。 - 测试基本交互：启动 CLI 并输入一个简单的 prompt，如 “Explain what a callback function is”，观察是否能正常返回响应。如果卡在 “Connecting...” 阶段，很可能是网络请求库的子依赖未打全。
6.2 常见问题与排查
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
Error: Cannot find module 'xxx' |
依赖树不完整，某中间层包未被缓存 | 回到外网构建机，检查 package-lock.json 中对应包的完整依赖链，用 npm pack 补全缺失的 tarball |
Error: /lib64/libc.so.6: version GLIBC_2.28 not found |
native addon 与目标系统 glibc 版本不匹配 | 在与目标机器相同操作系统的 Docker 容器中重新编译 native 模块，或切换为纯 JS 实现的替代包 |
CLI 启动后报 fetch is not defined |
Node.js 版本过低（<18）导致全局 fetch API 不可用 | 升级 Node.js 到 18 LTS 或更高版本；如果无法升级，在入口脚本顶部添加 globalThis.fetch = require('node-fetch') 作为 polyfill |
.node 文件加载失败 |
打包机器与目标机器的 CPU 架构或 Node.js ABI 版本不一致 | 确保在相同架构（x86_64/arm64）和 Node.js 版本下执行 npm rebuild 后再打包 |
6.3 网络隔离验证
最彻底的验证方式是在完全断开外网连接的环境中重放一次完整安装流程。可以将目标机器上的默认网关临时移除（sudo ip route del default），再执行安装命令。如果过程中没有任何超时报错，说明离线包已经自包含。
7. 总结与最佳实践建议
本文从内网开发的现实需求出发，完整梳理了 Claude Code 离线安装的必要性、包结构分析、依赖缓存策略、端到端实战流程以及私服化部署方案。将其中的关键经验提炼为以下最佳实践：
- 一次打包，多次分发：在外网构建机上完成依赖全量缓存后，将 tarball 归档文件和私服存储目录作为标准制品纳入版本管理，后续任何内网机器都可以直接复用，避免重复劳动。
- 锁定版本，拒绝漂移：离线包制作时必须严格基于
package-lock.json或npm-shrinkwrap.json，确保内网安装的依赖版本与构建时完全一致，杜绝因版本漂移导致的隐性问题。 - 架构对齐，提前验证：打包环境与目标环境保持一致（操作系统、glibc 版本、Node.js 大版本、CPU 架构），native addon 尽量用 Docker 容器统一编译，避免跨平台兼容性踩坑。
- 私服兜底，走向自动化：临时手动拷贝
.tgz适合小规模验证，长期维护务必搭建 Verdaccio 或复用企业制品仓库，配合 CI/CD 流水线实现依赖缓存的自动更新和分发。 - 建立离线安装检查清单：将第 6 章的验证步骤固化为团队的 checklist 文档，每次部署或新人入职时逐项核对，从流程上杜绝依赖缺失类的低级故障。
掌握了这套方法，无论是 Claude Code 还是其他 npm 生态下的 CLI 工具，都可以顺畅地在隔离环境中落地，在享受 AI 编程助手带来的效率提升的同时，也守住企业安全与合规的底线。