简介面向无法直连外网但需调用局域网大模型的开发团队这套离线安装包集中整理了Claude Code工具链及配套运行环境覆盖Git、Node.js、Python、VS Code、对应插件与vivado-mcp扩展可在企业内网完成全流程部署。压缩包共32个文件大小约616MB主要包含exe、whl、msi、vsix等类型可执行安装器负责各基础组件的静默安装whl文件补齐Python依赖库vsix插件封装编辑器集成功能zip压缩包提供完整源码与扩展配置另有PowerShell脚本和Markdown文档辅助批量部署与排错。组件均通过SHA256校验与数字签名验证兼容Windows、Linux、macOS主流环境内置证书信任链与本地模型加载模块可预先注入局域网模型服务地址适合运维或算法人员从零搭建离线AI开发环境。目前已有511人学习下载目录结构清晰既能支撑局域网大模型场景快速落地也为后续扩展Python报表生成、FPGA调试等专项能力保留现成基座是一套可长期维护的内网开发底座。1. 为什么 Claude Code 也需要提前准备离线安装包一上来就拦路的在线升级与权限问题在一个网络受限的开发环境里搭 Claude Code第一道坎往往不是工具本身而是它的分发方式。Claude Code 是跑在 Node.js 上的命令行编程工具日常通过 npm 分发和升级网络通畅时一条命令能装完网络不通时连安装都变得无法预测。更需要离线安装包的场景是内网开发机、白名单测试环境和给团队统一锁版本的交付场景。提前准备好离线安装包是为了让部署可预期装哪个版本、装到哪个目录、依赖是否齐全、升级会不会打断当前任务。这里会从要准备哪几样东西讲起用两条可复现的打包迁移路径装进 Windows 和 Linux再处理密钥、第三方模型接入和高频报错适合内网环境维护工程师也适合要做统一交付的团队。2. 离线安装包里到底该装什么拆解依赖、运行时与配置的三层边界很多人准备离线安装包时会下意识想“下载一个 exe 或 tgz 就完事”Claude Code 并不是这种分发模型。它本身是一个 npm 包安装时会铺开一层依赖树运行前还需要 Node.js 运行时和用户目录下的配置。这三层都齐了离线环境才能真正跑起来缺一层就会在某个阶段报一个看似莫名其妙的错误。先把边界拆清楚后面打包才不会漏东西。2.1 npm 包与依赖树只拷一个 tgz 是不行的Claude Code 的官方标准安装命令是npm install -g anthropic-ai/claude-code这条命令会把可执行脚本和一堆依赖铺进 npm 的全局目录。常见的错误想法是用npm pack打一个 tgz拷到离线机器再npm install -g ./xxx.tgz。这个思路对纯零依赖的小工具成立但对 Claude Code 这种依赖树较深的包不成立。npm pack只打包包本身不含传递依赖离线安装到一半就会因为缺依赖而失败。在联网机器上先看一下它到底需要什么再决定怎么打包# 查看直接依赖和可执行入口 npm view anthropic-ai/claude-code dependencies --json npm view anthropic-ai/claude-code bin --json这两条命令分别返回依赖列表和安装后生成的命令名。看到dependencies不是空对象就应该意识到离线打包不能只带一个 tgz而要带上整个 node_modules 依赖树。bin字段则告诉我们装完后 PATH 里会多出哪个命令一般是claudeWindows 下对应还会生成claude.cmd。后续验证命令是否存在就要盯着这个名字。全局安装目录本身就是一个完整的依赖树快照。我一般会直接以npm prefix -g返回的目录为单位做整体打包这样最不容易漏依赖。不要手动去 node_modules 里挑三五层目录漏掉一个传递依赖离线机器上就会报Cannot find module。另一个常用操作是把npm config get prefix和node -v先记录下来离线机器配 PATH 时要参考这些值。2.2 Node.js 运行时版本与原生模块决定能不能跑离线安装包里第二层是 Node.js 运行时。Claude Code 对 Node 版本有要求选太老的系统自带版本启动时会直接抛语法错误版本太新又可能踩到某些原生模块的兼容问题。常见做法是选 LTS 版本具体最低版本以你拿到的包发布说明为准。离线机器上通常不会预装合适的 Node所以要在联网机器上提前把安装包下载好。我一般会把 Node 二进制和 Claude Code 离线包放在一起分发# 在联网机器上下载 Node.js 二进制按目标系统选择 x64 或 arm64 curl -LO https://nodejs.org/dist/Node版本号/node-Node版本号-linux-x64.tar.xz tar -xJf node-Node版本号-linux-x64.tar.xz -C /opt/node export PATH/opt/node/node-Node版本号-linux-x64/bin:$PATH node -v npm -v下载时最容易翻车的点有两个一是下载了 arm64 构建却拷到 x64 的机器上二是解压到 /opt 后忘了把 bin 目录写进 PATH。node -v和npm -v两条命令就是用来验证运行时可用的先确认 Node 环境正常再继续装 Claude Code排查时至少能排除一半问题。这里还有一个离线安装的额外收益版本不会漂移。在线环境里npm install -g anthropic-ai/claude-code默认装 latest今天装和下周装可能是两个版本而离线包只要锁定了 Node 和 Claude Code 的版本行为就是确定的。这也是团队交付时更愿意维护离线包而不是让每个人在线安装的原因。Windows 离线机器则下载对应的 .msi 或 zip 包。WSL 环境不建议复用 Windows 的 Node文件系统不同后面会专门说。2.3 用户目录里的配置密钥、授权与缓存的隐性依赖第三层容易被忽略Claude Code 首次运行时会在用户主目录下生成配置目录常见位置是~/.claude/里面保存 settings.json、授权信息、对话历史和本地缓存。离线机器的用户主目录是全新的第一次执行 claude 时会表现出“命令能启动但一直在等认证”的状态。所以离线安装包实际要准备的第三样东西是运行配置。最简单的方式是直接在环境变量里给密钥也可以在~/.claude/settings.json里统一写好{ env: { ANTHROPIC_API_KEY: 替换成你的密钥, ANTHROPIC_BASE_URL: http://内部网关地址 } }把这份文件放到离线机器的~/.claude/下能少掉很多交互式输入。这里只铺底详细的环境变量和模型参数后面展开。需要提醒的是settings.json 里的内容属于敏感信息分发时要么用占位符让每个使用者自己填要么放在内网受限目录里别把密钥原文打进离线包。密钥文件一旦随包扩散范围和后果都不好控制。除了 settings.json~/.claude下还有记录会话历史的目录如果使用者希望保留之前的对话上下文离线迁移时也要把这个目录一并带走。但对话历史里可能包含代码片段拷贝前要确认内容允许流转。到这里三层边界已经清楚了依赖树、Node 运行时、用户配置缺一不可。3. 从联网机器到离线机器两条可复现的打包迁移路径前面把三层边界拆开了依赖树、Node 运行时、用户配置。这一章给两条真正能落地的打包路径。第一条适合快速交付和单人维护把 npm 全局目录整体搬过去第二条适合团队协作用固定版本和独立目录把工具链隔离起来。两条路径不冲突建议先读一遍再按你的环境选一条。3.1 路径一整体拷贝 npm 全局目录最省心但跨平台要小心路径一的思路很简单联网机器上先把包正常全局安装好然后以 npm 全局目录为边界压缩、拷贝、解压。这条路径对依赖树的完整性最友好因为 npm 已经把依赖铺平在全局目录里拷贝过去的就是一个能运行的状态。先在联网机器上执行# 安装并锁定一个明确的版本 npm install -g anthropic-ai/claude-code版本号 # 确认全局目录路径打包以此为根 npm prefix -g tar -czf claude-code-global.tar.gz -C $(npm prefix -g) .第一行里的版本号换成你要交付的版本号。npm prefix -g打印的是 npm 全局安装根目录在 Linux 上通常是/usr/local如果用了 nvm 则是用户目录下某条路径。第三行的-C参数让 tar 先切到那个目录再打包这样包内路径是相对路径解压到另一台机器同样位置时不会套多一层目录。把压缩包拷贝到离线 Linux 机器后# 解压到同一全局目录 sudo tar -xzf claude-code-global.tar.gz -C $(npm prefix -g) # 验证命令与版本 hash -r claude --version这里的hash -r是为了清掉 shell 里旧的命令路径缓存避免明明装了新命令shell 还记着之前“找不到”的结果。claude --version能跑通说明解压位置正确、脚本有可执行权限、依赖目录完整。如果提示找不到命令优先检查npm prefix -g结果是否和打包机器一致以及 PATH 里有没有包含全局 bin 目录。Windows 机器之间迁移同理但命令换成 PowerShell 写法npm install -g anthropic-ai/claude-code版本号 npm prefix -g tar -czf claude-code-global.tar.gz -C $(npm prefix -g) .离线机器上解压到相同路径后打开新终端窗口执行claude --version。注意 Windows 的系统自带 tar 在较老版本上路径解析有差异如果解压后目录层级对不上直接用文件管理器复制全局目录下的 node_modules 和 claude 启动脚本反而更快。3.2 路径二固定版本的项目级目录不动全局不动 PATH路径一虽然省心但它是“全局安装目录”的复制版本升级时会把旧版本覆盖掉想回滚往往要先找备份。对需要同时维护多个项目的团队我更喜欢路径二在联网机器上做一个固定版本的项目目录把 Claude Code 作为项目依赖装进去连同依赖树一起打包。离线机器上不需要全局安装只要把这个目录解压出来再从.bin里建一个软链就能当全局命令用。联网机器上这样准备mkdir -p /data/cc-fixed cd /data/cc-fixed npm init -y npm install --save-exact anthropic-ai/claude-code版本号 tar -czf cc-fixed.tar.gz package.json package-lock.json node_modules这里的--save-exact确保 package.json 里记录的是精确版本不带^号避免后续别人在这个目录里重新 install 时被解析到其他版本。node_modules是整个依赖树的可运行快照npm 安装项目依赖时会在node_modules/.bin下生成 claude 的可执行软链打包时带上它就够了。离线机器上的还原步骤mkdir -p /data/cc-fixed tar -xzf cc-fixed.tar.gz -C /data/cc-fixed cd /data/cc-fixed npm ls --depth0 ln -s /data/cc-fixed/node_modules/.bin/claude /usr/local/bin/claudenpm ls --depth0用来核对顶层依赖是否完整软链.bin/claude到/usr/local/bin后才可以在任意目录直接敲claude。要回滚时只要把软链改指到上一版目录即可比覆盖全局目录安全得多。路径二的代价是第一次打包时要求联网机器环境干净避免带进来多余依赖但它和持续集成流水线配合很好离线包可以像普通工件一样按版本号归档。团队里多人共用时每个人拿到的都是同一份依赖树不会再出现“我本地能跑你本地不能跑”的版本不一致问题。3.3 Windows 原生与 WSL 的安装差异两条环境两条路很多人的电脑同时有 Windows 原生终端和 WSL以为在一边装好另一边就能用。这是一个高频误解Windows 原生的 npm 全局目录和 WSLLinux的文件系统是两套WSL 里敲claude是找不到的。在 WSL 里应该重新执行一次离线解压npm prefix -g sudo mkdir -p $(npm prefix -g) sudo tar -xzf claude-code-global.tar.gz -C $(npm prefix -g) claude --version注意这里要确认打包来源是 Linux 版不能把 Windows 机器打包出来的目录直接塞进 WSL。两者差异会体现在启动脚本格式和原生模块上。还要留意的点是如果你用 VS Code 连 WSL 终端它读的是 WSL 的 PATH不是 Windows 的 PATH在 VS Code 里看到command not found先确认当前打开的是哪个环境的终端再去对应的环境里修 PATH。4. 装完不等于能跑密钥配置与第三方模型接入的常见做法离线包把工具和依赖装好只说明“文件就位了”。真正要让 Claude Code 干活还要让它的请求能到达模型服务。这一章处理两件事一是最基础的密钥配置二是把请求转发到内部网关或兼容服务时的参数调整。4.1 先让 claude 命令能启动API 密钥怎么传Claude Code 的认证在离线环境里有两种可依赖的方式。第一种是环境变量简单直接适合当前 shell 会话要立即用的情况export ANTHROPIC_API_KEY你的密钥 claude第二种是把密钥写进用户配置这样每次启动不用重复设置。配置文件位置在~/.claude/settings.json写法前面已经出现过。两者的优先级需要留意环境变量通常会覆盖配置文件里的同名项如果你在配置文件里写了旧密钥shell 又 export 了新密钥生效的是新密钥排查认证报错时先确认当前会话到底加载了哪个。还有一点如果这台离线机器是多人共用的不要把密钥直接写在全局配置里。我一般会在配置里留占位符或者要求使用者自己 export宁可每次多敲一次也避免密钥跟着账号共享出去。首次启动建议先带-p参数做一次单次请求验证确认通了再进交互界面否则交互模式卡在认证等待上更难判断问题。4.2 把请求转发到兼容接口Base URL 与模型参数设置如果你的模型服务部署在内网或者接的是兼容 Anthropic 消息协议的服务商网关只要改几个环境变量Claude Code 就可以把请求转发过去离线包本身不用重新打。核心是三个变量export ANTHROPIC_BASE_URLhttp://网关根地址 export ANTHROPIC_AUTH_TOKEN网关令牌 export ANTHROPIC_API_KEY任意非空占位 claude --model 模型标识这里最容易踩的坑是ANTHROPIC_BASE_URL的路径。Claude Code 的请求逻辑会在基础地址后面拼接/v1/messages之类的具体路径所以基础地址应该填网关根地址不要自己把/v1/messages也带上。带上了网关会路由失败表现就是请求发出后返回 404 或not_found。第二个坑是部分网关只看ANTHROPIC_AUTH_TOKEN不看 API_KEY如果网关只认 AUTH_TOKENAPI_KEY 可以随意填一个非空值如果网关两个头都校验则需要都填对。遇到 401 就逐个变量试。模型参数方面命令行--model每次指定最灵活想让整个离线环境固定用某个模型在~/.claude/settings.json里写默认值{ model: 模型标识, env: { ANTHROPIC_BASE_URL: http://网关根地址, ANTHROPIC_AUTH_TOKEN: 网关令牌 } }这里的“模型标识”取决于后端服务支持的模型名不同网关的叫法可能不一样务必以服务方文档为准。设置完先跑一次最小请求验证不要直接进交互界面。4.3 离线环境下的版本验证一个能用的最小检查清单离线环境排查问题成本高因为不方便临时联网查资料。我习惯在装完任何东西后跑一组固定命令做冒烟验证node -v npm -v claude --version claude --help | head -20 claude --model 模型标识 -p 只回复两个字在线前两条确认运行时正常第三条确认 CLI 主程序完整第四条确认帮助信息能加载如果依赖缺失往往在这里就报错。最后一条真正发起一次请求同时验证了密钥、网关地址、模型标识和网络连通性。如果最后一条失败先看报错类别command not found是 PATH 问题authentication_error是密钥或令牌问题not_found十有八九是 base_url 路径写多了超时则是从离线机器到网关的网络没通。这里还需要专门提醒离线环境测试时要注意有没有代理类环境变量在干扰请求。某些环境下HTTP_PROXY或HTTPS_PROXY指向了一个不可达的代理claude 的请求会被强制走代理然后超时。遇到连不上的情况先执行env | grep -i proxy看一眼必要时在启动命令前临时清掉这些变量。5. 离线安装 Claude Code 的避坑指南五个高频翻车现场这里集中写离线安装和后续使用里最容易反复折腾的五个问题。每条都按现象、原因、解决的顺序展开你可以直接按当前看到什么报错来对号入座。5.1 现象Auto-update failed: no write permission to npm prefix很多人在离线机器上装完 Claude Code第一次启动就出现类似auto-update failed: no write permission to npm prefix的提示。Claude Code 会尝试自动升级而 npm 全局目录对当前用户不可写时升级就会失败。原因通常是这台离线机器的 Node 是用系统包管理器装的/usr/local或 nvm 之外的全局目录属于 root 用户当前普通用户没有写权限。在线环境里很多人用sudo npm install -g绕过但在离线机器上自动升级机制绕不过权限。解决方法是把 npm 全局目录改到用户可写的地方然后把离线包解压到新位置npm config get prefix npm config set prefix $HOME/.npm-global export PATH$HOME/.npm-global/bin:$PATH mkdir -p $HOME/.npm-global tar -xzf claude-code-global.tar.gz -C $HOME/.npm-global claude --version改完 prefix 相当于换了新的全局根目录原来的旧全局目录可以留着不动。要注意把 PATH 导出写进~/.bashrc或~/.profile否则下次开终端又找不回 claude 命令。5.2 现象离线安装时还在尝试访问网络离线机器上执行npm install --offline anthropic-ai/claude-code结果卡了很久最终报ETIMEDOUT或者request to https://registry.npmjs.org failed。这看起来像 npm 没有真正离线。原因是--offline只保证 npm 不会主动发起 tarball 下载但某些依赖的元数据在本地缓存里缺失时npm 仍然会尝试去 registry 拿最新元数据尤其在 package-lock.json 不完整的情况下。离线包如果不带完整的_cacache缓存这个坑几乎必踩。解决方法是不要依赖 npm 的离线模式改用整体目录拷贝方式把已经安装好的 node_modules 完整搬过去。如果非要走 npm 离线模式需要把联网机器的完整 npm 缓存目录~/.npm/_cacache一起拷贝到离线机器并保证 package-lock.json 完整再用npm ci --offline还原。验证是否真的离线把网线拔掉跑一次安装是最靠谱的办法。5.3 现象装完找不到 claude 命令离线机器上解压完目录也执行了claude --version但新开的终端里却报command not found。原因通常是 PATH 没有包含 npm 全局 bin 目录或者 shell 缓存了旧的查找结果。另一种常见情况是 VS Code 的集成终端在启动时读的是老的 PATH安装完没重启终端。解决分两步先确认当前 shell 能不能找到再看 PATHwhich claude echo $PATH hash -r claude --version如果which claude没有输出说明 PATH 里确实没有全局 bin。Linux 下把 export 写进 shell 配置文件Windows 下检查环境变量里有没有%APPDATA%\npm改完要新开终端再试。如果which claude有输出但 shell 还是报找不到那就是缓存问题hash -r清一下就好。另外一种隐蔽情况是离线机器上有多个 Node 环境前缀路径被 nvm 或某个版本管理器切到了别处。用npm prefix -g看当前实际全局目录跟你解压的目标目录对不上就是这个原因。5.4 现象接第三方模型后请求 403/404模型网关配好后请求发出去不是 403 就是 404而且错误信息不一定直观。403 大概率是认证问题。可能原因网关要求的是ANTHROPIC_AUTH_TOKEN你只设了ANTHROPIC_API_KEY或者两个变量都设了但网关只认其中一个另一个优先级反而覆盖了正确的。解决方法是看网关文档确认它读取哪个请求头然后把对应的环境变量设为正确值另一个设置成占位符或不设置。404 则大概率是路径问题。ANTHROPIC_BASE_URL带上了/v1/messages后缀网关按根路径的路由规则转发找不到对应路由就返回 404。把 base_url 改成网关根地址后再试。如果网关本身要求完整路径需要确认它对外暴露的根路径是什么再决定是否要在配置里加一层反向代理把路径修正掉。5.5 现象WSL 里报 Invalid ELF headerWSL 环境下从 Windows 共享盘或者某个 Windows 目录里解压 claude-code 全局目录启动时直接报Invalid ELF header或Cannot find module。原因是把 Windows 下安装的原生模块复制到了 Linux 环境.node这种编译产物在两种系统里格式完全不同WSL 里的 Node 加载到 Windows 版原生模块第一反应就是 ELF 头不合法。反之把 Linux 版全局目录拷到 Windows 原生环境也会出现类似问题。解决方法是保持“同类环境用同类包”Windows 用 Windows 包WSL 用 Linux 包不要跨系统复制 node_modules。如果你需要在 Windows 和 WSL 里都能用就分别准备两个离线包各自解压到各自环境的全局目录。平台无关的配置文件如 settings.json 可以共用一份但注意路径写法要跟着环境调整。6. 更进一步的实用技巧给团队做一份可复用的离线工作台6.1 固定版本的内部安装源结构当离线机器不止一两台时我建议把离线安装包组织成一个固定结构放内网共享盘或内部文件服务器上cc-offline-repo/ ├── node-版本号-linux-x64.tar.xz ├── node-版本号-win-x64.zip ├── cc-fixed-版本号.tar.gz ├── verify.sh └── README.mdREADME 里固定写清楚三件事先装 Node再解压 Claude Code 离线包最后配密钥和网关。每个文件都用版本号命名升级时新增文件、保留旧文件。这样任何人拿到目录照着 README 一步步做不会再出现“装完了找不到命令”这类低级问题。6.2 一条命令完成安装自检在上面的目录结构里放一个verify.sh内容就是前面那组冒烟命令只是加上了明确的退出码#!/usr/bin/env bash set -e MODEL${1:-} node -v npm -v claude --version if [ -n $MODEL ]; then claude --model $MODEL -p 只回复两个字在线 fi echo 离线安装验证通过团队里任何人安装完执行bash verify.sh 模型标识如果最后能看到“验证通过”说明整条链路是通的哪一步失败输出来的是哪个报错排查起来非常省事。如果不传模型标识脚本只做到 CLI 层面验证传了模型标识就会把密钥、网关和模型名全部验一遍。这个脚本配合版本号目录就构成了一套最简单的内部发布流程。我把离线版本号管理这件事养成习惯之后最明显的收益是再也不用在问题现场猜“他用的到底是哪个版本”。升级前先在离线测试机上跑一遍完整验证确认依赖和网关都没问题再把新版本号目录同步给其他人旧版本目录留一个月再清理相当于给自己留了后悔药。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/9 14:46:35 · 阅读 1.2k Claude Code离线安装与内网部署：依赖树、Node运行时与配置迁移指南
简介面向无法直连外网但需调用局域网大模型的开发团队这套离线安装包集中整理了Claude Code工具链及配套运行环境覆盖Git、Node.js、Python、VS Code、对应插件与vivado-mcp扩展可在企业内网完成全流程部署。压缩包共32个文件大小约616MB主要包含exe、whl、msi、vsix等类型可执行安装器负责各基础组件的静默安装whl文件补齐Python依赖库vsix插件封装编辑器集成功能zip压缩包提供完整源码与扩展配置另有PowerShell脚本和Markdown文档辅助批量部署与排错。组件均通过SHA256校验与数字签名验证兼容Windows、Linux、macOS主流环境内置证书信任链与本地模型加载模块可预先注入局域网模型服务地址适合运维或算法人员从零搭建离线AI开发环境。目前已有511人学习下载目录结构清晰既能支撑局域网大模型场景快速落地也为后续扩展Python报表生成、FPGA调试等专项能力保留现成基座是一套可长期维护的内网开发底座。1. 为什么 Claude Code 也需要提前准备离线安装包一上来就拦路的在线升级与权限问题在一个网络受限的开发环境里搭 Claude Code第一道坎往往不是工具本身而是它的分发方式。Claude Code 是跑在 Node.js 上的命令行编程工具日常通过 npm 分发和升级网络通畅时一条命令能装完网络不通时连安装都变得无法预测。更需要离线安装包的场景是内网开发机、白名单测试环境和给团队统一锁版本的交付场景。提前准备好离线安装包是为了让部署可预期装哪个版本、装到哪个目录、依赖是否齐全、升级会不会打断当前任务。这里会从要准备哪几样东西讲起用两条可复现的打包迁移路径装进 Windows 和 Linux再处理密钥、第三方模型接入和高频报错适合内网环境维护工程师也适合要做统一交付的团队。2. 离线安装包里到底该装什么拆解依赖、运行时与配置的三层边界很多人准备离线安装包时会下意识想“下载一个 exe 或 tgz 就完事”Claude Code 并不是这种分发模型。它本身是一个 npm 包安装时会铺开一层依赖树运行前还需要 Node.js 运行时和用户目录下的配置。这三层都齐了离线环境才能真正跑起来缺一层就会在某个阶段报一个看似莫名其妙的错误。先把边界拆清楚后面打包才不会漏东西。2.1 npm 包与依赖树只拷一个 tgz 是不行的Claude Code 的官方标准安装命令是npm install -g anthropic-ai/claude-code这条命令会把可执行脚本和一堆依赖铺进 npm 的全局目录。常见的错误想法是用npm pack打一个 tgz拷到离线机器再npm install -g ./xxx.tgz。这个思路对纯零依赖的小工具成立但对 Claude Code 这种依赖树较深的包不成立。npm pack只打包包本身不含传递依赖离线安装到一半就会因为缺依赖而失败。在联网机器上先看一下它到底需要什么再决定怎么打包# 查看直接依赖和可执行入口 npm view anthropic-ai/claude-code dependencies --json npm view anthropic-ai/claude-code bin --json这两条命令分别返回依赖列表和安装后生成的命令名。看到dependencies不是空对象就应该意识到离线打包不能只带一个 tgz而要带上整个 node_modules 依赖树。bin字段则告诉我们装完后 PATH 里会多出哪个命令一般是claudeWindows 下对应还会生成claude.cmd。后续验证命令是否存在就要盯着这个名字。全局安装目录本身就是一个完整的依赖树快照。我一般会直接以npm prefix -g返回的目录为单位做整体打包这样最不容易漏依赖。不要手动去 node_modules 里挑三五层目录漏掉一个传递依赖离线机器上就会报Cannot find module。另一个常用操作是把npm config get prefix和node -v先记录下来离线机器配 PATH 时要参考这些值。2.2 Node.js 运行时版本与原生模块决定能不能跑离线安装包里第二层是 Node.js 运行时。Claude Code 对 Node 版本有要求选太老的系统自带版本启动时会直接抛语法错误版本太新又可能踩到某些原生模块的兼容问题。常见做法是选 LTS 版本具体最低版本以你拿到的包发布说明为准。离线机器上通常不会预装合适的 Node所以要在联网机器上提前把安装包下载好。我一般会把 Node 二进制和 Claude Code 离线包放在一起分发# 在联网机器上下载 Node.js 二进制按目标系统选择 x64 或 arm64 curl -LO https://nodejs.org/dist/Node版本号/node-Node版本号-linux-x64.tar.xz tar -xJf node-Node版本号-linux-x64.tar.xz -C /opt/node export PATH/opt/node/node-Node版本号-linux-x64/bin:$PATH node -v npm -v下载时最容易翻车的点有两个一是下载了 arm64 构建却拷到 x64 的机器上二是解压到 /opt 后忘了把 bin 目录写进 PATH。node -v和npm -v两条命令就是用来验证运行时可用的先确认 Node 环境正常再继续装 Claude Code排查时至少能排除一半问题。这里还有一个离线安装的额外收益版本不会漂移。在线环境里npm install -g anthropic-ai/claude-code默认装 latest今天装和下周装可能是两个版本而离线包只要锁定了 Node 和 Claude Code 的版本行为就是确定的。这也是团队交付时更愿意维护离线包而不是让每个人在线安装的原因。Windows 离线机器则下载对应的 .msi 或 zip 包。WSL 环境不建议复用 Windows 的 Node文件系统不同后面会专门说。2.3 用户目录里的配置密钥、授权与缓存的隐性依赖第三层容易被忽略Claude Code 首次运行时会在用户主目录下生成配置目录常见位置是~/.claude/里面保存 settings.json、授权信息、对话历史和本地缓存。离线机器的用户主目录是全新的第一次执行 claude 时会表现出“命令能启动但一直在等认证”的状态。所以离线安装包实际要准备的第三样东西是运行配置。最简单的方式是直接在环境变量里给密钥也可以在~/.claude/settings.json里统一写好{ env: { ANTHROPIC_API_KEY: 替换成你的密钥, ANTHROPIC_BASE_URL: http://内部网关地址 } }把这份文件放到离线机器的~/.claude/下能少掉很多交互式输入。这里只铺底详细的环境变量和模型参数后面展开。需要提醒的是settings.json 里的内容属于敏感信息分发时要么用占位符让每个使用者自己填要么放在内网受限目录里别把密钥原文打进离线包。密钥文件一旦随包扩散范围和后果都不好控制。除了 settings.json~/.claude下还有记录会话历史的目录如果使用者希望保留之前的对话上下文离线迁移时也要把这个目录一并带走。但对话历史里可能包含代码片段拷贝前要确认内容允许流转。到这里三层边界已经清楚了依赖树、Node 运行时、用户配置缺一不可。3. 从联网机器到离线机器两条可复现的打包迁移路径前面把三层边界拆开了依赖树、Node 运行时、用户配置。这一章给两条真正能落地的打包路径。第一条适合快速交付和单人维护把 npm 全局目录整体搬过去第二条适合团队协作用固定版本和独立目录把工具链隔离起来。两条路径不冲突建议先读一遍再按你的环境选一条。3.1 路径一整体拷贝 npm 全局目录最省心但跨平台要小心路径一的思路很简单联网机器上先把包正常全局安装好然后以 npm 全局目录为边界压缩、拷贝、解压。这条路径对依赖树的完整性最友好因为 npm 已经把依赖铺平在全局目录里拷贝过去的就是一个能运行的状态。先在联网机器上执行# 安装并锁定一个明确的版本 npm install -g anthropic-ai/claude-code版本号 # 确认全局目录路径打包以此为根 npm prefix -g tar -czf claude-code-global.tar.gz -C $(npm prefix -g) .第一行里的版本号换成你要交付的版本号。npm prefix -g打印的是 npm 全局安装根目录在 Linux 上通常是/usr/local如果用了 nvm 则是用户目录下某条路径。第三行的-C参数让 tar 先切到那个目录再打包这样包内路径是相对路径解压到另一台机器同样位置时不会套多一层目录。把压缩包拷贝到离线 Linux 机器后# 解压到同一全局目录 sudo tar -xzf claude-code-global.tar.gz -C $(npm prefix -g) # 验证命令与版本 hash -r claude --version这里的hash -r是为了清掉 shell 里旧的命令路径缓存避免明明装了新命令shell 还记着之前“找不到”的结果。claude --version能跑通说明解压位置正确、脚本有可执行权限、依赖目录完整。如果提示找不到命令优先检查npm prefix -g结果是否和打包机器一致以及 PATH 里有没有包含全局 bin 目录。Windows 机器之间迁移同理但命令换成 PowerShell 写法npm install -g anthropic-ai/claude-code版本号 npm prefix -g tar -czf claude-code-global.tar.gz -C $(npm prefix -g) .离线机器上解压到相同路径后打开新终端窗口执行claude --version。注意 Windows 的系统自带 tar 在较老版本上路径解析有差异如果解压后目录层级对不上直接用文件管理器复制全局目录下的 node_modules 和 claude 启动脚本反而更快。3.2 路径二固定版本的项目级目录不动全局不动 PATH路径一虽然省心但它是“全局安装目录”的复制版本升级时会把旧版本覆盖掉想回滚往往要先找备份。对需要同时维护多个项目的团队我更喜欢路径二在联网机器上做一个固定版本的项目目录把 Claude Code 作为项目依赖装进去连同依赖树一起打包。离线机器上不需要全局安装只要把这个目录解压出来再从.bin里建一个软链就能当全局命令用。联网机器上这样准备mkdir -p /data/cc-fixed cd /data/cc-fixed npm init -y npm install --save-exact anthropic-ai/claude-code版本号 tar -czf cc-fixed.tar.gz package.json package-lock.json node_modules这里的--save-exact确保 package.json 里记录的是精确版本不带^号避免后续别人在这个目录里重新 install 时被解析到其他版本。node_modules是整个依赖树的可运行快照npm 安装项目依赖时会在node_modules/.bin下生成 claude 的可执行软链打包时带上它就够了。离线机器上的还原步骤mkdir -p /data/cc-fixed tar -xzf cc-fixed.tar.gz -C /data/cc-fixed cd /data/cc-fixed npm ls --depth0 ln -s /data/cc-fixed/node_modules/.bin/claude /usr/local/bin/claudenpm ls --depth0用来核对顶层依赖是否完整软链.bin/claude到/usr/local/bin后才可以在任意目录直接敲claude。要回滚时只要把软链改指到上一版目录即可比覆盖全局目录安全得多。路径二的代价是第一次打包时要求联网机器环境干净避免带进来多余依赖但它和持续集成流水线配合很好离线包可以像普通工件一样按版本号归档。团队里多人共用时每个人拿到的都是同一份依赖树不会再出现“我本地能跑你本地不能跑”的版本不一致问题。3.3 Windows 原生与 WSL 的安装差异两条环境两条路很多人的电脑同时有 Windows 原生终端和 WSL以为在一边装好另一边就能用。这是一个高频误解Windows 原生的 npm 全局目录和 WSLLinux的文件系统是两套WSL 里敲claude是找不到的。在 WSL 里应该重新执行一次离线解压npm prefix -g sudo mkdir -p $(npm prefix -g) sudo tar -xzf claude-code-global.tar.gz -C $(npm prefix -g) claude --version注意这里要确认打包来源是 Linux 版不能把 Windows 机器打包出来的目录直接塞进 WSL。两者差异会体现在启动脚本格式和原生模块上。还要留意的点是如果你用 VS Code 连 WSL 终端它读的是 WSL 的 PATH不是 Windows 的 PATH在 VS Code 里看到command not found先确认当前打开的是哪个环境的终端再去对应的环境里修 PATH。4. 装完不等于能跑密钥配置与第三方模型接入的常见做法离线包把工具和依赖装好只说明“文件就位了”。真正要让 Claude Code 干活还要让它的请求能到达模型服务。这一章处理两件事一是最基础的密钥配置二是把请求转发到内部网关或兼容服务时的参数调整。4.1 先让 claude 命令能启动API 密钥怎么传Claude Code 的认证在离线环境里有两种可依赖的方式。第一种是环境变量简单直接适合当前 shell 会话要立即用的情况export ANTHROPIC_API_KEY你的密钥 claude第二种是把密钥写进用户配置这样每次启动不用重复设置。配置文件位置在~/.claude/settings.json写法前面已经出现过。两者的优先级需要留意环境变量通常会覆盖配置文件里的同名项如果你在配置文件里写了旧密钥shell 又 export 了新密钥生效的是新密钥排查认证报错时先确认当前会话到底加载了哪个。还有一点如果这台离线机器是多人共用的不要把密钥直接写在全局配置里。我一般会在配置里留占位符或者要求使用者自己 export宁可每次多敲一次也避免密钥跟着账号共享出去。首次启动建议先带-p参数做一次单次请求验证确认通了再进交互界面否则交互模式卡在认证等待上更难判断问题。4.2 把请求转发到兼容接口Base URL 与模型参数设置如果你的模型服务部署在内网或者接的是兼容 Anthropic 消息协议的服务商网关只要改几个环境变量Claude Code 就可以把请求转发过去离线包本身不用重新打。核心是三个变量export ANTHROPIC_BASE_URLhttp://网关根地址 export ANTHROPIC_AUTH_TOKEN网关令牌 export ANTHROPIC_API_KEY任意非空占位 claude --model 模型标识这里最容易踩的坑是ANTHROPIC_BASE_URL的路径。Claude Code 的请求逻辑会在基础地址后面拼接/v1/messages之类的具体路径所以基础地址应该填网关根地址不要自己把/v1/messages也带上。带上了网关会路由失败表现就是请求发出后返回 404 或not_found。第二个坑是部分网关只看ANTHROPIC_AUTH_TOKEN不看 API_KEY如果网关只认 AUTH_TOKENAPI_KEY 可以随意填一个非空值如果网关两个头都校验则需要都填对。遇到 401 就逐个变量试。模型参数方面命令行--model每次指定最灵活想让整个离线环境固定用某个模型在~/.claude/settings.json里写默认值{ model: 模型标识, env: { ANTHROPIC_BASE_URL: http://网关根地址, ANTHROPIC_AUTH_TOKEN: 网关令牌 } }这里的“模型标识”取决于后端服务支持的模型名不同网关的叫法可能不一样务必以服务方文档为准。设置完先跑一次最小请求验证不要直接进交互界面。4.3 离线环境下的版本验证一个能用的最小检查清单离线环境排查问题成本高因为不方便临时联网查资料。我习惯在装完任何东西后跑一组固定命令做冒烟验证node -v npm -v claude --version claude --help | head -20 claude --model 模型标识 -p 只回复两个字在线前两条确认运行时正常第三条确认 CLI 主程序完整第四条确认帮助信息能加载如果依赖缺失往往在这里就报错。最后一条真正发起一次请求同时验证了密钥、网关地址、模型标识和网络连通性。如果最后一条失败先看报错类别command not found是 PATH 问题authentication_error是密钥或令牌问题not_found十有八九是 base_url 路径写多了超时则是从离线机器到网关的网络没通。这里还需要专门提醒离线环境测试时要注意有没有代理类环境变量在干扰请求。某些环境下HTTP_PROXY或HTTPS_PROXY指向了一个不可达的代理claude 的请求会被强制走代理然后超时。遇到连不上的情况先执行env | grep -i proxy看一眼必要时在启动命令前临时清掉这些变量。5. 离线安装 Claude Code 的避坑指南五个高频翻车现场这里集中写离线安装和后续使用里最容易反复折腾的五个问题。每条都按现象、原因、解决的顺序展开你可以直接按当前看到什么报错来对号入座。5.1 现象Auto-update failed: no write permission to npm prefix很多人在离线机器上装完 Claude Code第一次启动就出现类似auto-update failed: no write permission to npm prefix的提示。Claude Code 会尝试自动升级而 npm 全局目录对当前用户不可写时升级就会失败。原因通常是这台离线机器的 Node 是用系统包管理器装的/usr/local或 nvm 之外的全局目录属于 root 用户当前普通用户没有写权限。在线环境里很多人用sudo npm install -g绕过但在离线机器上自动升级机制绕不过权限。解决方法是把 npm 全局目录改到用户可写的地方然后把离线包解压到新位置npm config get prefix npm config set prefix $HOME/.npm-global export PATH$HOME/.npm-global/bin:$PATH mkdir -p $HOME/.npm-global tar -xzf claude-code-global.tar.gz -C $HOME/.npm-global claude --version改完 prefix 相当于换了新的全局根目录原来的旧全局目录可以留着不动。要注意把 PATH 导出写进~/.bashrc或~/.profile否则下次开终端又找不回 claude 命令。5.2 现象离线安装时还在尝试访问网络离线机器上执行npm install --offline anthropic-ai/claude-code结果卡了很久最终报ETIMEDOUT或者request to https://registry.npmjs.org failed。这看起来像 npm 没有真正离线。原因是--offline只保证 npm 不会主动发起 tarball 下载但某些依赖的元数据在本地缓存里缺失时npm 仍然会尝试去 registry 拿最新元数据尤其在 package-lock.json 不完整的情况下。离线包如果不带完整的_cacache缓存这个坑几乎必踩。解决方法是不要依赖 npm 的离线模式改用整体目录拷贝方式把已经安装好的 node_modules 完整搬过去。如果非要走 npm 离线模式需要把联网机器的完整 npm 缓存目录~/.npm/_cacache一起拷贝到离线机器并保证 package-lock.json 完整再用npm ci --offline还原。验证是否真的离线把网线拔掉跑一次安装是最靠谱的办法。5.3 现象装完找不到 claude 命令离线机器上解压完目录也执行了claude --version但新开的终端里却报command not found。原因通常是 PATH 没有包含 npm 全局 bin 目录或者 shell 缓存了旧的查找结果。另一种常见情况是 VS Code 的集成终端在启动时读的是老的 PATH安装完没重启终端。解决分两步先确认当前 shell 能不能找到再看 PATHwhich claude echo $PATH hash -r claude --version如果which claude没有输出说明 PATH 里确实没有全局 bin。Linux 下把 export 写进 shell 配置文件Windows 下检查环境变量里有没有%APPDATA%\npm改完要新开终端再试。如果which claude有输出但 shell 还是报找不到那就是缓存问题hash -r清一下就好。另外一种隐蔽情况是离线机器上有多个 Node 环境前缀路径被 nvm 或某个版本管理器切到了别处。用npm prefix -g看当前实际全局目录跟你解压的目标目录对不上就是这个原因。5.4 现象接第三方模型后请求 403/404模型网关配好后请求发出去不是 403 就是 404而且错误信息不一定直观。403 大概率是认证问题。可能原因网关要求的是ANTHROPIC_AUTH_TOKEN你只设了ANTHROPIC_API_KEY或者两个变量都设了但网关只认其中一个另一个优先级反而覆盖了正确的。解决方法是看网关文档确认它读取哪个请求头然后把对应的环境变量设为正确值另一个设置成占位符或不设置。404 则大概率是路径问题。ANTHROPIC_BASE_URL带上了/v1/messages后缀网关按根路径的路由规则转发找不到对应路由就返回 404。把 base_url 改成网关根地址后再试。如果网关本身要求完整路径需要确认它对外暴露的根路径是什么再决定是否要在配置里加一层反向代理把路径修正掉。5.5 现象WSL 里报 Invalid ELF headerWSL 环境下从 Windows 共享盘或者某个 Windows 目录里解压 claude-code 全局目录启动时直接报Invalid ELF header或Cannot find module。原因是把 Windows 下安装的原生模块复制到了 Linux 环境.node这种编译产物在两种系统里格式完全不同WSL 里的 Node 加载到 Windows 版原生模块第一反应就是 ELF 头不合法。反之把 Linux 版全局目录拷到 Windows 原生环境也会出现类似问题。解决方法是保持“同类环境用同类包”Windows 用 Windows 包WSL 用 Linux 包不要跨系统复制 node_modules。如果你需要在 Windows 和 WSL 里都能用就分别准备两个离线包各自解压到各自环境的全局目录。平台无关的配置文件如 settings.json 可以共用一份但注意路径写法要跟着环境调整。6. 更进一步的实用技巧给团队做一份可复用的离线工作台6.1 固定版本的内部安装源结构当离线机器不止一两台时我建议把离线安装包组织成一个固定结构放内网共享盘或内部文件服务器上cc-offline-repo/ ├── node-版本号-linux-x64.tar.xz ├── node-版本号-win-x64.zip ├── cc-fixed-版本号.tar.gz ├── verify.sh └── README.mdREADME 里固定写清楚三件事先装 Node再解压 Claude Code 离线包最后配密钥和网关。每个文件都用版本号命名升级时新增文件、保留旧文件。这样任何人拿到目录照着 README 一步步做不会再出现“装完了找不到命令”这类低级问题。6.2 一条命令完成安装自检在上面的目录结构里放一个verify.sh内容就是前面那组冒烟命令只是加上了明确的退出码#!/usr/bin/env bash set -e MODEL${1:-} node -v npm -v claude --version if [ -n $MODEL ]; then claude --model $MODEL -p 只回复两个字在线 fi echo 离线安装验证通过团队里任何人安装完执行bash verify.sh 模型标识如果最后能看到“验证通过”说明整条链路是通的哪一步失败输出来的是哪个报错排查起来非常省事。如果不传模型标识脚本只做到 CLI 层面验证传了模型标识就会把密钥、网关和模型名全部验一遍。这个脚本配合版本号目录就构成了一套最简单的内部发布流程。我把离线版本号管理这件事养成习惯之后最明显的收益是再也不用在问题现场猜“他用的到底是哪个版本”。升级前先在离线测试机上跑一遍完整验证确认依赖和网关都没问题再把新版本号目录同步给其他人旧版本目录留一个月再清理相当于给自己留了后悔药。希望帮到你。本文还有配套的精品资源点击获取