Claude Code 离线安装方案揭秘：从环境准备到实战部署

1. 引言

Claude Code 是 Anthropic 推出的 AI 编程助手，面向代码理解、修改、调试和项目级协作等开发场景进行了深度优化。然而，在企业内网、离线环境或受控网络中，直接通过 npm 在线安装往往不可行。本文将深入揭秘 Claude Code 的离线安装全流程，从依赖分析、包缓存、镜像搭建到完整部署，提供可复现的实战方案。

2. 离线安装的核心挑战

Claude Code 基于 Node.js 生态，其安装依赖包括：

• Node.js 运行时：需要 v18+ 版本
• npm 包依赖：@anthropic-ai/claude-code 及其 transitive dependencies
• 系统依赖：git、glibc 版本兼容性等
• 认证与配置：API Key 或代理配置

离线安装的核心思路是：在联网机器上完整下载所有依赖，打包传输到离线环境，再通过本地源或直接解压完成安装。

3. 环境准备

3.1 联网机器（构建机）

# 确认 Node.js 版本 node --version # 需 ≥ 18.0.0 npm --version # 需 ≥ 9.0.0 创建离线包工作目录 mkdir -p ~/claude-code-offline cd ~/claude-code-offline

3.2 离线目标机

# 确认系统架构 uname -m # x86_64 或 aarch64 cat /etc/os-release # 确认发行版和 glibc 版本

4. 方案一：npm 离线缓存（推荐）

4.1 在构建机上完整下载

# 初始化项目 npm init -y 安装 Claude Code（会下载所有依赖到 node_modules） npm install @anthropic-ai/claude-code 生成完整离线缓存（将所有包打包为 .tgz） npm pack @anthropic-ai/claude-code 输出类似：anthropic-ai-claude-code-0.1.0.tgz 导出所有 transitive 依赖的缓存 npm cache ls 2>/dev/null || true 更可靠的方式：直接打包 node_modules tar -czf claude-code-offline.tar.gz node_modules package.json package-lock.json

4.2 传输到离线环境

# 使用 scp、U盘或内部文件服务器传输 scp claude-code-offline.tar.gz user@offline-server:/tmp/ 或通过内部 HTTP 服务器分发 在构建机上启动临时服务 cd ~/claude-code-offline python3 -m http.server 8080 在离线机上通过 wget 下载（如果离线机有内部网络） wget http://build-server:8080/claude-code-offline.tar.gz

4.3 在离线目标机上安装

# 解压离线包 mkdir -p ~/claude-code cd ~/claude-code tar -xzf /tmp/claude-code-offline.tar.gz 创建本地链接（无需重新 npm install） cd ~/claude-code npm install --offline --no-audit --no-fund 验证安装 npx @anthropic-ai/claude-code --version 创建全局软链接（可选） sudo ln -s ~/claude-code/node_modules/.bin/claude-code /usr/local/bin/claude-code claude-code --version

5. 方案二：搭建私有 npm 镜像（适合团队）

5.1 使用 Verdaccio 搭建本地源

# 在内部服务器上安装 Verdaccio npm install -g verdaccio 启动服务（默认监听 4873） verdaccio & 配置 npm 指向本地源 npm set registry http://internal-server:4873/

5.2 在构建机上发布包到私有源

# 登录私有源（首次需要创建用户） npm adduser --registry http://internal-server:4873/ 发布 Claude Code 包 cd ~/claude-code-offline npm publish --registry http://internal-server:4873/ 发布所有 transitive 依赖（需要脚本批量处理） 以下脚本将 node_modules 中所有包发布到私有源 for pkg in node_modules/*/; do if [ -f "$pkg/package.json" ]; then cd "$pkg" npm publish --registry http://internal-server:4873/ 2>/dev/null || true cd - fi done

5.3 在离线机上从私有源安装

# 配置 npm 指向内部私有源 npm set registry http://internal-server:4873/ 安装 Claude Code npm install -g @anthropic-ai/claude-code 验证 claude-code --version

6. 方案三：全静态二进制打包（无 Node.js 依赖）

对于完全没有 Node.js 运行时的环境，可以使用 pkg 或 nexe 将 Claude Code 打包为独立可执行文件。

6.1 在构建机上打包

# 安装打包工具 npm install -g pkg 进入 Claude Code 目录 cd ~/claude-code-offline/node_modules/@anthropic-ai/claude-code 打包为 Linux x64 可执行文件 pkg . --targets node18-linux-x64 --output ~/claude-code-offline/claude-code-bin 打包为 Linux ARM64 pkg . --targets node18-linux-arm64 --output ~/claude-code-offline/claude-code-bin-arm

6.2 在离线机上直接运行

# 传输二进制文件到离线机 # 直接运行（无需 Node.js） chmod +x claude-code-bin ./claude-code-bin --version 移动到系统路径 sudo mv claude-code-bin /usr/local/bin/claude-code claude-code --version

7. 配置与认证

7.1 设置 API Key

# 方式一：环境变量 export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx" 方式二：配置文件 mkdir -p ~/.config/claude cat > ~/.config/claude/config.yaml << 'EOF' api_key: "sk-ant-xxxxxxxxxxxx" model: "claude-sonnet-4-20250514" EOF

7.2 配置代理（如果离线环境有出网代理）

export HTTP_PROXY="http://proxy.internal:8080" export HTTPS_PROXY="http://proxy.internal:8080" export NO_PROXY="localhost,127.0.0.1,internal.domain"

8. 完整自动化脚本

以下是一个一键式离线安装脚本，整合了上述所有步骤：

#!/bin/bash # claude-code-offline-install.sh # 用法：在离线机上运行 # chmod +x claude-code-offline-install.sh # ./claude-code-offline-install.sh set -euo pipefail OFFLINE_PACKAGE_URL="${1:-http://build-server:8080/claude-code-offline.tar.gz}" INSTALL_DIR="${2:-$HOME/claude-code}" echo "[1/5] 下载离线包..." mkdir -p "$INSTALL_DIR" cd "$INSTALL_DIR" wget -q "$OFFLINE_PACKAGE_URL" -O offline-package.tar.gz echo "[2/5] 解压..." tar -xzf offline-package.tar.gz echo "[3/5] 离线安装依赖..." npm install --offline --no-audit --no-fund --no-optional echo "[4/5] 创建软链接..." sudo ln -sf "$INSTALL_DIR/node_modules/.bin/claude-code" /usr/local/bin/claude-code echo "[5/5] 验证安装..." claude-code --version echo "✅ Claude Code 离线安装完成！" echo "请设置 ANTHROPIC_API_KEY 环境变量后使用。"

9. 常见问题排查

10. 总结

本文详细介绍了三种 Claude Code 离线安装方案：

• npm 离线缓存方案：适合单机或小团队，操作简单，依赖完整
• 私有 npm 镜像方案：适合企业级团队，支持版本管理和多机分发
• 静态二进制打包方案：适合无 Node.js 运行时的极端环境

建议优先使用方案一（npm 离线缓存），它在灵活性和可靠性之间取得了最佳平衡。对于需要长期维护的企业环境，方案二（私有镜像）更为合适。无论选择哪种方案，都建议在正式部署前先在测试环境完整验证一遍流程。