在现代软件开发中，无论是构建C++项目的前端界面，还是部署基于JavaScript、TypeScript的后端服务，npm（Node Package Manager）已成为不可或缺的依赖管理工具。然而，在企业内网、安全隔离环境或网络受限场景下，如何高效、可靠地完成npm包的离线安装，是每个开发者都可能面临的挑战。本文将以离线安装Claude Code客户端及其路由组件为例，为你详细拆解一套通用、可复用的npm离线安装方法论，这套方法同样适用于Java、Go等其他语言生态中基于npm的前端工具链部署。

一、离线安装的核心挑战与npm原生方案优势

传统的离线安装往往通过手动下载包再复制，但这种方式存在明显缺陷：容易遗漏深层嵌套的间接依赖，且无法自动处理平台特异性（如win32、linux、darwin）。npm原生命令提供了一套优雅的解决方案，其核心优势在于：

  • ✅ 依赖树完整性：自动解析并获取所有直接与间接依赖，形成完整清单。
  • ✅ 智能平台过滤：根据执行环境自动筛选所需平台包，避免下载无用资源。
  • ✅ 版本精确锁定：确保离线环境与线上环境的依赖版本完全一致，避免“在我机器上能运行”的问题。

无论是为大型Java应用配置前端监控工具，还是为Go服务部署Web管理界面，这套流程都能确保依赖的完整性和一致性。[AFFILIATE_SLOT_1]

二、三步走实战：从生成清单到离线部署

整个离线安装流程可精炼为三个清晰步骤，我们以安装 @anthropic-ai/claude-code 和 @musistudio/claude-code-router 为例进行说明。

步骤一：在有网环境生成完整依赖清单

首先，需要在一台能够访问npm仓库的机器上，创建一个临时项目并安装目标包。执行以下命令后，npm会为我们完成所有繁重的依赖分析工作：

# 进入项目目录（包含 package.json 和 package-lock.json）
cd /path/to/project
# 安装依赖（生成 node_modules，npm 会自动选择当前平台的包）
npm install
# 生成完整的依赖清单（包含所有直接和间接依赖）
# --all: 显示所有传递依赖
# --json: 以 JSON 格式输出
npm ls --all --json > deps-full.json

此命令的妙处在于，它不仅安装了包，更关键的是生成了一个名为 deps-full.json 的文件。这个文件包含了整个依赖树的完整快照。其结构示例如下：

{
"dependencies": {
"@anthropic-ai/claude-code": {
"version": "2.1.15",
"resolved": "http://nexus.test.com/.../claude-code-2.1.15.tgz",
"dependencies": {
"@img/sharp-win32-x64": {
"version": "0.33.5",
"resolved": "http://nexus.test.com/.../sharp-win32-x64-0.33.5.tgz"
}
}
},
"@musistudio/claude-code-router": {
"version": "2.0.0",
"resolved": "http://nexus.test.com/.../claude-code-router-2.0.0.tgz"
}
}
}

如示例所示，

说明： 已经自动过滤了平台，只下载了当前系统需要的包

。这份清单是我们后续所有操作的“蓝图”，务必妥善保管。

步骤二：解析清单并下载离线包文件

有了依赖清单，下一步是将其转化为具体的.tgz压缩包文件。我们需要从清单中提取出每个包的确切名称和版本号。原理是：

提示：如果依赖包数量较少（例如少于 5 个），推荐直接从浏览器下载 文件，比使用命令行工具更简单快捷。

。

在同一台有网机器上，执行以下脚本，即可批量下载所有必需的.tgz文件到本地目录：

# 1. 从 deps-full.json 中提取所有 resolved 链接
# Windows PowerShell:
Get-Content deps-full.json | Select-String '"resolved"' | ForEach-Object {
if ($_ -match '"resolved":\s*"([^"]+)"') {
$matches[1]
}
} | Out-File -Encoding utf8 download-urls.txt
# Linux/macOS/Git Bash:
grep -o '"resolved":\s*"[^"]*"' deps-full.json | sed 's/"resolved":\s*"\([^"]*\)"/\1/' > download-urls.txt
# 2. 批量下载 .tgz 文件
# 使用 aria2c (推荐):
aria2c -i download-urls.txt -d offline-packages
# 或使用 wget:
wget -i download-urls.txt -P offline-packages
# 或使用 curl:
cat download-urls.txt | xargs -I {} curl -O --create-dirs --output-dir offline-packages {}
# 3. 复制依赖清单到离线包目录（供参考）
cp deps-full.json offline-packages/

最佳实践：建议将下载的.tgz文件按项目或日期归档，方便后续管理与复用，这在为多个TypeScript项目准备离线依赖时尤其高效。

步骤三：在离线环境完成最终安装

将上一步下载的所有.tgz文件以及deps-full.json清单拷贝至离线机器。在离线机器上，我们无需网络，直接指向本地文件进行安装。核心命令如下：

# 1. 进入 offline-packages 目录
cd offline-packages
# 2. 查看依赖清单（了解需要安装的包）
cat deps-full.json
# 3. 安装所有 .tgz 包到全局
#    Windows PowerShell (必须使用 PowerShell，CMD 不支持 *.tgz 通配符):
npm install -g (Get-ChildItem *.tgz) --offline
#    Linux/macOS/Git Bash:
npm install -g *.tgz --offline
# 4. 验证安装
claude --version
ccr --version
npm list -g --depth=0

这里的关键是

重要提示：

  • Windows 用户必须使用 PowerShell，CMD 不支持通配符展开
  • 不要使用 CMD，否则会报错
。对于批量安装，可以使用简单的Shell循环，npm会智能处理包之间的依赖顺序，无需手动排序。

三、命令详解、注意事项与跨平台策略

为了更灵活地控制离线安装流程，以下是一些核心命令的参考，你可以根据实际需求组合使用：

依赖分析相关命令：用于深入检查依赖关系。

命令说明
安装依赖到 node_modules（自动过滤平台）
显示所有依赖（包括传递依赖）
以 JSON 格式输出依赖树
以机器可读格式输出

包下载相关命令：用于获取包文件本身。

命令说明
提取 resolved 链接
批量下载（推荐）
批量下载
下载单个文件

离线安装相关命令：在无网环境的核心操作。

命令说明
安装单个包到全局
批量安装（仅 Windows PowerShell，CMD 不支持 *.tgz 通配符）
批量安装（仅 Linux/macOS/Git Bash）
查看已安装的全局包

⚠️ 关键注意事项：

  1. 平台一致性原则：这是最容易出错的地方。确保生成依赖清单的机器（有网机）与最终安装的机器（离线机）操作系统一致。因为npm install过程会自动过滤平台包。如果需要在Windows、Linux、macOS上部署，必须在每种平台上分别执行步骤一和步骤二，生成三套不同的离线包。
  2. Shell环境适配：批量安装命令需根据终端环境稍作调整。例如：
    Windows PowerShell: npm install -g (Get-ChildItem *.tgz)
    Git Bash / Linux / macOS: npm install -g *.tgz

详细的Shell命令对照表如下：

平台推荐Shell不支持说明
WindowsPowerShellCMDCMD 不支持通配符
WindowsGit Bash-可用，与 Linux 相同
LinuxBash/sh-原生支持
macOSBash/zsh-原生支持

正如

Windows 用户注意：CMD 不支持 通配符，必须使用 PowerShell

所强调的，预先在有网环境执行npm install是整套流程智能化的基石，它自动解决了平台适配和依赖树展开两大难题。[AFFILIATE_SLOT_2]

四、总结与扩展应用

掌握npm离线安装技术，意味着你能够：

  • 在任何无外网环境（如客户生产网、保密研发中心）部署Node.js应用或前端工具。
  • 为CI/CD流水线预先准备依赖缓存，极大加速构建过程，这对Java、Go项目的容器化构建镜像制作非常有用。
  • 实现依赖的版本固化与安全审计，所有依赖均来自一次性的、经过验证的下载。

本文以Claude Code为例，但所述方法100%适用于任何通过npm分发的包，无论是React组件库、Vue CLI插件、TypeScript类型定义文件，还是Electron应用、Node.js后端服务。通过将依赖清单（deps-full.json）和离线包（.tgz）纳入版本管理或制品库，你可以构建起一套稳定、可重复、高效率的离线开发部署体系，彻底摆脱网络环境的束缚。

npm install.tgznpm installnpm ls --allnpm ls --all --jsonnpm ls --all --parseablegrep -o '"resolved":\s*"[^"]*"' file.jsonaria2c -i urls.txt -d dirwget -i urls.txt -P dircurl -O --output-dir dirnpm install -g package.tgznpm install -g (Get-ChildItem *.tgz)npm install -g *.tgznpm list -g --depth=0*.tgz*.tgz ---

推荐阅读

以下资源可以帮助你进一步提升：