npm 离线安装软件包指南（离线安装 claude code）

本文以离线安装 @anthropic-ai/claude-code（Claude Code 客户端）和 @musistudio/claude-code-router（Claude Code Router）为例，介绍如何通过 npm 原生命令实现离线全局安装。该方法适用于任何 npm 包的离线安装场景。

流程概览

1. 使用 npm 命令生成完整的依赖清单（包含直接和间接依赖）
2. 从依赖清单中解析出需要下载的包名和版本
3. 下载对应的 .tgz 文件并安装到全局

---

步骤一：生成依赖清单

在有网机器上执行

# 进入项目目录（包含 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"
    }
  }
}

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

---

步骤二：从清单解析并下载 .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/

---

步骤三：离线安装

在离线机器上执行

重要提示：

• Windows 用户必须使用 PowerShell，CMD 不支持通配符展开
• 不要使用 CMD，否则会报错

# 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

---

命令参考

依赖分析相关

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

下载相关

命令	说明
grep -o '"resolved":\s*"[^"]*"' file.json	提取 resolved 链接
aria2c -i urls.txt -d dir	批量下载（推荐）
wget -i urls.txt -P dir	批量下载
curl -O --output-dir dir	下载单个文件

安装相关

命令	说明
npm install -g package.tgz	安装单个包到全局
npm install -g (Get-ChildItem *.tgz)	批量安装（仅 Windows PowerShell，CMD 不支持 *.tgz 通配符）
npm install -g *.tgz	批量安装（仅 Linux/macOS/Git Bash）
npm list -g --depth=0	查看已安装的全局包

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

---

优势说明

为什么先执行 npm install？

1. 自动平台过滤：npm 会根据当前系统自动选择需要的包

   • Windows 只下载 win32 相关的包
   • Linux 只下载 linux 相关的包
   • macOS 只下载 darwin 相关的包

2. 获取完整依赖树 ：npm ls --all --json 会显示所有直接和间接依赖

3. 避免下载无用包：不需要下载其他平台的包，节省时间和空间

---

注意事项

1. 平台一致性

确保有网机器和离线机器是相同平台：

• 如果有网机器是 Windows，离线机器也应该是 Windows
• 如果有网机器是 Linux，离线机器也应该是 Linux

如果需要跨平台，需要在每个平台上分别执行步骤一和步骤二。

2. Shell 环境要求

平台	推荐Shell	不支持	说明
Windows	PowerShell	CMD	CMD 不支持通配符 *.tgz
Windows	Git Bash	-	可用，与 Linux 相同
Linux	Bash/sh	-	原生支持
macOS	Bash/zsh	-	原生支持

批量安装命令：

• Windows PowerShell: npm install -g (Get-ChildItem *.tgz)
• Windows Git Bash/Linux/macOS: npm install -g *.tgz

3. 依赖顺序

使用批量安装命令时，npm 会自动处理依赖顺序，无需手动排序。

---

（END）