离线环境部署 pnpm 前端开发环境教程

by emanjusaka from https://www.emanjusaka.com/archives/offline-pnpm-project-transfer 彼岸花开可奈何
本文为原创文章，可能会更新教程以及修正文中的一些错误，全文转载请保留原文地址，避免产生因未即时修正导致的误导。

博客：https://www.emanjusaka.com
博客园：https://www.cnblogs.com/emanjusaka
公众号：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。