离线环境部署 pnpm 前端开发环境教程
作者：毅念安（Inian / Emanjusaka）｜原创，后续会更新修正，转载请保留原文链接。
📝 独立博客：https://www.emanjusaka.com｜博客园：https://www.cnblogs.com/emanjusaka｜公众号：毅念安
当我们需要在一台完全断网的电脑上面需要调试或者开发一个使用 pnpm 管理依赖的前端项目时，应该怎么把需要的依赖搬运过去。
本文将提供一种"自包含"方案，让整个开发工具箱完全跟随项目走，脱离对全局环境的依赖，也不需要任何网络连接。
一、方案思路
把 Node.js、pnpm 和所有依赖包都变成项目的一部分，打包成一个可移动的整体。
在有网的电脑上，把 pnpm 的缓存目录设置在项目内，安装所有依赖
下载 Node.js 免安装版
用保留硬链接的方式打包整个项目
在离线电脑上解压项目，直接用项目内的 Node 和 pnpm 启动开发服务
二、预先准备
1、下载免安装的 Node.js
在官网 上下载对应操作系统和架构的二进制压缩包，解压后就是一个免安装的 Node.js 环境。
2、配置让 pnpm store 留在项目内
在项目根目录下修改（如果没有就新建.npmrc 文件，添加一行：
store-dir = ./pnpm-store
这样 pnpm 的全局缓存就会被写入项目目录下的 pnpm-store 文件夹，而不是系统用户目录，方便整体搬运。
3、将 pnpm 本身也装成项目依赖
为了让离线电脑不需要预先安装 pnpm，我们直接把它作为本地开发依赖：
pnpm add -D pnpm
这样 node_modules/.bin/pnpm 里就有一份可用的 pnpm，其自身也会被缓存到 pnpm-store 中。
4、 安装所有项目依赖
pnpm install
确认 node_modules 正常生成，pnpm-lock.yaml 完整。此时所有依赖源码已经全部躺在项目自己的 pnpm-store 里。
5、（可选）清理多余缓存
如果想减小体积，可以删掉与本项目无关的缓存包：
pnpm store prune
6、打包项目（推荐保留硬链接）
pnpm 在 node_modules 和 pnpm-store 之间大量使用硬链接来节约磁盘空间。打包时保住这种结构，既能控制体积，又能保证解压后文件完整性。
推荐使用 tar：
tar -czf project-offline.tar.gz .
Linux / macOS 下直接运行即可。
如果在 Windows 上，可以用 7-Zip 先打包成 tar，再压缩；或直接在 WSL 中操作。
虽然 zip 也能用（硬链接会被转成普通副本，体积变大），但不影响最终运行。
7、最终交付物
把下面两个文件拷贝到移动介质（U 盘、移动硬盘等）：
Node.js
project-offline.tar.gz （项目镜像）
三、离线部署
1、解压 Node.js
解压 Node.js 压缩包到一个固定位置，比如 ~/node。
可以选择将 ~/node/bin 加入环境变量 PATH，或者后面直接用绝对路径调用。
2、解压项目
将项目解压到一个固定位置，比如~/my-project
3、启动项目
由于 pnpm 已经在 node_modules 里，直接用刚解压的 Node 去调它即可：
# 方法一：直接调用 pnpm 的入口文件
~/node/bin/node node_modules/pnpm/bin/pnpm.cjs dev
# 方法二：用 npx（它会自动找到本地的 pnpm，不会联网）
~/node/bin/npx pnpm dev
如果之前已经将 ~/node/bin 加入了 PATH，那直接运行：
node node_modules/pnpm/bin/pnpm.cjs dev
# 或
npx pnpm dev
4、后续安装其他依赖（仅限 store 已有的包）
假如你需要添加一个已经在 pnpm-store 中缓存过的包，可以离线执行：
node node_modules/pnpm/bin/pnpm.cjs add <package-name> --offline
注意：如果 store 里没有这个包，命令会失败，因为无网络可下载。
四、注意事项与踩坑提示
- 系统必须一致
如果在线机器是 Linux x64，离线电脑也必须是 Linux x64；macOS ARM 到 macOS ARM 同理。否则含有原生模块（如node-sass、esbuild等）的依赖会加载失败。
如果不得已需要跨平台，可在联网机器上使用 Docker 模拟目标环境后执行pnpm install。
