1. 为什么要在内网离线环境折腾 Claude Code先把场景说清楚。很多做开发的朋友第一次听到“内网离线部署 Claude Code”脑子里冒出来的第一个问题是这玩意儿不是联网用的吗离线怎么跑其实这里说的“离线”指的是安装过程不依赖公网而不是说模型推理本身要断网。真实场景通常是这样的公司研发网、实验室隔离网、金融或制造业的内网工位机器能访问内部制品库但出不了公网npm 装不了包官网下载页打不开。这时候你想在本地用上 Claude Code 这类命令行 AI 编程助手就得把整套依赖提前在能联网的机器上准备好再搬进内网。我前后在三种不同的隔离环境里做过这件事踩过的坑从 Node 版本不匹配到 npm 全局路径权限再到 PowerShell 执行策略拦截脚本基本把能遇到的都遇了一遍。这篇就把整套流程拆开讲透从依赖清单、离线包制作、环境变量配置到内网落地后的验证和排错全部给到可直接抄作业的程度。适合谁看三类人一是要在隔离网里搭开发环境的运维或平台工程师二是被内网限制卡住、想自己动手搞定的普通开发者三是负责给团队做统一工具链、需要写部署文档的技术负责人。哪怕你之前没怎么碰过 Node.js 和 npm跟着走也能落地因为我会把每个命令背后的意图讲清楚而不是甩一堆命令让你照敲。核心关键词先埋进来Claude Code、内网离线部署、Node.js、npm、环境变量。这五个词基本就是整条链路的骨架——Claude Code 是目标工具Node.js 和 npm 是它的运行底座离线部署是约束条件环境变量是把这一切串起来、让命令能在任意目录被找到的关键。理解了这五者的关系后面所有操作你都能自己推导。有一点必须提前说明Claude Code 官方对运行环境有版本要求Node.js 版本过低会直接报错比如常见的node:util does not provide an export named这类报错本质就是 Node 版本太老、缺少新 API。所以离线部署的第一原则是版本对齐联网机器和内网机器的 Node 大版本必须一致否则你搬进去的包可能根本跑不起来。2. 离线部署的整体思路与依赖清单拆解2.1 为什么选“整包搬运”而不是逐个下载离线部署有好几种做法一种是在内网自建 npm 私有仓库把依赖同步进去另一种是把全局包和 Node 运行时打包成压缩包直接拷贝。前者适合长期维护、团队规模大的场景后者适合“我就想快点用上”的个人或小团队。我推荐后者原因很实在自建私有仓库比如 Verdaccio 之类本身也要联网初始化、要维护、要处理依赖树对只想用工具的人来说是过度设计。而整包搬运的逻辑非常朴素——在联网机器上把 Node 运行时和全局 npm 包都装好然后把整个目录打包搬到内网解压配好环境变量就能用。整个过程不涉及任何在线请求天然适配隔离网。提示整包搬运的前提是两台机器的操作系统架构一致。联网机是 Windows x64内网机也得是 Windows x64如果一边是 ARM 一边是 x86二进制包不通用必须找对应架构的版本。2.2 依赖清单到底要准备哪些东西把这件事拆到最小需要准备的东西其实不多但每一样都不能少。我整理成一张表方便你对照检查依赖项作用是否必须备注Node.js 运行时提供 node 命令和 npm必须版本需满足 Claude Code 要求npm 全局包目录存放 Claude Code 及其依赖必须默认在用户目录下环境变量配置让命令全局可用必须PATH 是核心Git部分功能依赖版本控制建议内网也建议装终端工具运行命令行必须Windows Terminal 体验更好Node.js 是整个链路的地基。Claude Code 是跑在 Node 环境里的命令行工具没有 Node 就没有一切。npm 是 Node 自带的包管理器用来安装 Claude Code。环境变量决定了你在任意目录敲claude能不能被系统找到。Git 不是硬性要求但 Claude Code 很多能力跟代码仓库绑定内网里装一个 Git 会让体验完整很多。2.3 版本选择别用最新用最稳很多人有个误区觉得版本越新越好。离线部署恰恰相反要选经过验证的稳定版本。原因很简单你没法在内网随时升级一旦选了个有 bug 的版本排查成本极高。我的经验是Node.js 选 LTS长期支持版本比如 18.x 或 20.x 系列。Claude Code 对 Node 版本有下限要求低于这个线会直接报模块导出错误。你在联网机器上先确认版本node -v npm -v把这两个版本号记下来内网机器必须装同一个大版本。如果内网机器已经装了旧版 Node要么升级要么把旧版彻底卸载干净再装新版别让两个版本共存否则 PATH 里指向哪个全看运气非常容易出玄学问题。3. 联网机器上的准备工作把包做出来3.1 安装 Node.js 并验证在能联网的机器上去 Node.js 官网下载对应系统的安装包。Windows 用户下.msi一路下一步即可安装时注意勾选“Add to PATH”这样环境变量会自动配好。macOS 用户可以用官方.pkgLinux 用户建议用官方二进制包解压避免包管理器版本太旧。装完打开终端验证node -v npm -v两条命令都能输出版本号说明基础环境 OK。如果提示“不是内部或外部命令”说明 PATH 没配好这时候别急着往下走先把环境变量搞定否则后面全是坑。3.2 配置 npm 镜像源加速下载联网机器上装包默认源有时候慢得让人抓狂。可以临时切到国内镜像源加速注意这只是为了加快下载跟离线部署本身无关npm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认。这一步纯粹是提升制作离线包的效率内网机器不需要也不能配这个因为它访问不了。3.3 全局安装 Claude Code关键一步来了。Claude Code 要全局安装这样它的可执行文件才会进到全局 bin 目录方便打包搬运npm install -g anthropic-ai/claude-code安装过程中如果看到npm warn deprecated node-domexception1.0.0这类警告不用慌这是依赖包的废弃提示不影响功能。真正要警惕的是EBADENGINE或版本不兼容的报错那说明你的 Node 版本不对得先解决版本问题。装完验证claude --version能输出版本号说明安装成功。如果提示命令找不到八成是全局 bin 目录没进 PATH用npm config get prefix看看全局目录在哪手动确认一下。3.4 定位全局目录并打包现在要把成果打包。先找到 npm 全局目录npm config get prefixWindows 上通常类似C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 上通常是/usr/local或用户目录下的某个路径。这个目录里有两个关键子目录node_modules存放包本体根目录下有claude之类的可执行脚本。打包时把整个全局目录压缩同时别忘了 Node 运行时本身。Windows 上 Node 装在C:\Program Files\nodejs把这个目录也一起打包。最终你会得到两个压缩包一个是 Node 运行时一个是 npm 全局包目录。注意打包前先关掉所有终端避免文件被占用导致压缩不完整。压缩格式用 zip 或 tar.gz 都行内网机器能解压即可。4. 内网机器落地解压、配置、验证4.1 解压到固定路径内网机器上先把两个压缩包解压到固定路径。建议路径里不要有中文和空格比如D:\dev\nodejs和D:\dev\npm-global。中文路径在某些工具链里会引发编码问题空格会让环境变量配置变得麻烦能避就避。解压完D:\dev\nodejs下应该有node.exe、npm.cmd等文件D:\dev\npm-global下应该有node_modules和claude.cmd之类的脚本。确认这些文件都在再往下走。4.2 配置环境变量PATH 是核心环境变量配置是离线部署里最容易翻车的一环。核心就一件事把 Node 目录和 npm 全局目录都加进 PATH让系统在任何位置都能找到node、npm、claude这三个命令。Windows 上操作路径此电脑右键 → 属性 → 高级系统设置 → 环境变量。在“系统变量”里找到Path编辑新增两条D:\dev\nodejs D:\dev\npm-global保存后必须重开终端环境变量才会生效。很多人配完发现没反应就是因为没重开终端。macOS/Linux 上编辑~/.bashrc或~/.zshrc追加export PATH/opt/dev/nodejs/bin:$PATH export PATH/opt/dev/npm-global/bin:$PATH然后source ~/.bashrc让配置立即生效。4.3 验证三连node、npm、claude重开终端后依次验证node -v npm -v claude --version三条都能输出版本号说明离线部署基本成功。如果node和npm正常但claude找不到问题一定出在 npm 全局目录没进 PATH回去检查路径拼写和是否重开终端。如果claude能跑但报模块缺失说明打包时node_modules不完整需要回联网机器重新打包确保全局目录整个搬过来别只搬可执行脚本。4.4 内网环境变量配置的常见误区这里单独拎出来讲因为踩的人太多。第一个误区是只配用户变量不配系统变量导致换个用户登录就失效。第二个误区是路径末尾多加了反斜杠或分号Windows 对这类细节比较敏感。第三个误区是把 Node 目录和 npm 全局目录搞混两个都要加缺一不可。还有一个隐蔽的坑如果内网机器之前装过旧版 NodePATH 里可能残留旧路径且排在前面导致你敲node跑的还是旧版本。解决办法是把旧路径删掉或者把新路径挪到最前面。5. 常见报错与排查速查表5.1 PowerShell 脚本被禁止运行Windows 上敲npm报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这是 PowerShell 执行策略拦截了.ps1脚本。解决办法是改执行策略以管理员身份打开 PowerShellSet-ExecutionPolicy -Scope CurrentUser RemoteSigned确认后重开终端即可。RemoteSigned的意思是本地脚本可运行、远程脚本需签名安全性够用也不会把口子开太大。5.2 Node 版本过低导致的模块导出错误报错长这样node:util does not provide an export named这是典型的 Node 版本太老缺少新版本才有的 API。Claude Code 依赖较新的 Node 特性旧版本跑不动。解决办法就是升级 Node且联网机和内网机版本对齐。别想着打补丁绕过升级是最省事的。5.3 全局命令找不到claude提示“不是内部或外部命令”排查顺序先确认npm config get prefix输出的目录里有没有claude.cmd再确认这个目录在不在 PATH最后确认终端是否重开过。三步走完基本能定位。5.4 排查速查表报错现象可能原因解决方向npm.ps1 禁止运行PowerShell 执行策略改 RemoteSigned模块导出错误Node 版本过低升级并对齐版本claude 找不到全局目录未进 PATH检查 PATH 并重开终端命令跑的是旧版本PATH 残留旧路径删除旧路径或调整顺序解压后文件缺失打包不完整重新打包全局目录6. 内网使用体验优化与实操心得6.1 把配置固化成脚本内网机器可能不止一台每次手动配环境变量太累。我的做法是写一个批处理或 shell 脚本把 PATH 设置、验证命令都写进去新机器跑一遍脚本就搞定。这样既省时间也避免手抖配错。Windows 批处理示例echo off setx PATH %PATH%;D:\dev\nodejs;D:\dev\npm-global /M echo 环境变量已配置请重开终端/M表示写入系统变量需要管理员权限运行。6.2 版本管理留一份“黄金包”离线部署最怕的就是“这次能用下次换台机器就不行”。我的经验是第一次成功部署后把联网机器上的 Node 运行时和全局包目录原样再打一份包标注好版本号和日期存到内网共享盘里当作“黄金包”。以后新机器直接解压这个包版本完全一致省去所有对齐工作。6.3 关于 Git 和环境变量的补充内网里如果要用到版本控制相关功能Git 也得离线装。Git 的环境变量配置逻辑和 Node 类似把bin目录加进 PATH 即可。有些朋友会问 Java 环境变量怎么配其实逻辑是相通的——找到可执行文件所在目录加进 PATH重开终端验证。环境变量这套东西学一次能套用到所有命令行工具上。6.4 我踩过的几个真实坑第一个坑是打包时没关终端结果node_modules里有文件被占用压缩包缺文件内网解压后 Claude Code 跑不起来排查了半天才发现是打包不完整。第二个坑是内网机器 PATH 里旧 Node 路径没删导致命令跑的是旧版本报了一堆莫名其妙的错。第三个坑是用中文路径某个依赖读取路径时编码出错换成纯英文路径立刻正常。这些坑的共同点是都不是技术难题而是流程细节。离线部署的难点从来不在“会不会”而在“细不细”。把每一步的意图想清楚把版本对齐、路径干净、打包完整这三件事做到位基本就不会翻车。6.5 后续扩展思路这套方法不只适用于 Claude Code。任何基于 Node.js 的命令行工具都可以用同样的“整包搬运”思路做离线部署。你把 Node 运行时和全局包目录打包本质上就是做了一个自包含的运行环境。以后遇到类似需求换个包名就行流程完全复用。如果团队规模大、更新频繁可以考虑在内网搭一个轻量的私有 npm 仓库把常用包同步进去这样升级时不用每次重新打包。但对大多数个人和小团队来说整包搬运的性价比最高简单、直接、可控。最后分享一个我一直在用的小技巧在内网机器的全局目录里放一个README.txt写清楚这个包是什么版本、什么时候打的、对应哪台联网机器过几个月再回头看能省下大量回忆成本。离线环境没有网络帮你查证一切信息都得靠自己留痕。