内网环境下pnpm项目迁移指南
📌 前置条件
环境一致性要求
- ✅ Node.js版本必须保持一致
- ✅ package.json中的依赖版本必须保持一致
- ✅ pnpm版本必须保持一致或向下兼容
1️⃣ 环境准备
互联网设备操作
1.1 安装与项目匹配的pnpm版本
# 查看项目中使用的pnpm版本(查看package.json或pnpm-lock.yaml)
# 安装与项目完全一致的pnpm版本
npm i pnpm@<项目使用的版本号> --install-strategy=shallow
# 或安装不低于项目的版本(推荐)
npm i pnpm@">=<项目使用的版本号>" --install-strategy=shallow⚠️ 重要提醒:务必确保安装的pnpm版本与项目要求一致。曾有案例因版本差异导致项目无法运行,耗费一天时间排查!
1.2 配置pnpm存储路径
# 创建存储目录(根据实际磁盘情况调整)
mkdir D:\pnpm-store
# 配置pnpm存储路径
pnpm config set global-bin-dir "D:\pnpm-store"
pnpm config set cache-dir "D:\pnpm-store\pnpm-cache"
pnpm config set state-dir "D:\pnpm-store\pnpm-state"
pnpm config set global-dir "D:\pnpm-store\global"
pnpm config set store-dir "D:\pnpm-store\pnpm-store"📝 注意:此配置会影响后续依赖存储位置,内外网建议保持一致以便管理。
2️⃣ 联网环境安装依赖
2.1 进入项目目录并安装依赖
cd /path/to/your/project
pnpm install2.2 清理项目node_modules
# 删除项目中的node_modules文件夹(重要!)
rm -rf node_modules # Linux/Mac
# 或
rd /s /q node_modules # Windows📌 说明:pnpm安装时会在配置中写入绝对路径,此node_modules不能直接迁移使用!
3️⃣ 文件打包与传输
需要打包的内容:
完整的项目代码(已删除node_modules)
- 包含
pnpm-lock.yaml文件(重要!) - 包含所有源代码和配置文件
- 包含
- pnpm全局存储目录:
D:\pnpm-store(整个目录)
打包步骤:
# 压缩项目文件夹(排除node_modules)
tar -czf project.tar.gz /path/to/project --exclude=node_modules
# 压缩整个pnpm存储目录
tar -czf pnpm-store.tar.gz D:\pnpm-store📦 传输注意:
- 将两个压缩包传输到内网设备
- 项目可以放在任意路径,但建议与原开发环境结构相似
4️⃣ 内网设备配置
4.1 安装pnpm(版本必须一致!)
# 如果已有打包的pnpm全局安装包
npm i -g pnpm/
# 或重新安装指定版本
npm i pnpm@<指定版本>4.2 解决IDE中pnpm命令识别问题
如果在CMD中可以执行pnpm,但IDE(如WebStorm、VSCode)提示命令不存在:
解决方案:
- 重启电脑(最有效)
如果不想重启,尝试:
# 手动刷新环境变量 refreshenv # Windows(需要安装Chocolatey或手动执行) # 或重启IDE- 在IDE中重新打开终端
- 检查IDE的终端设置,确保使用的是系统终端而非内置终端
⚠️ 重要:第一次安装pnpm后强烈建议重启电脑,因为环境变量更新需要重新加载!
4.3 配置存储路径
# 建议配置与联网设备相同的路径
pnpm config set store-dir "D:\pnpm-store\pnpm-store"
pnpm config set cache-dir "D:\pnpm-store\pnpm-cache"5️⃣ 内网项目恢复
5.1 解压文件
# 解压项目到内网开发目录
tar -xzf project.tar.gz -C /your/internal/path
# 解压pnpm存储
tar -xzf pnpm-store.tar.gz -C D:\5.2 安装项目依赖
# 进入项目目录
cd /your/internal/path/project
# 安装依赖(会从本地store读取)
pnpm install --offline如果出现依赖问题,可以尝试:
# 清除缓存并重新安装
pnpm store prune
pnpm install🔧 常见问题解决
问题1:版本不一致导致错误
现象:安装或运行时出现版本相关错误
解决:确保内外网所有版本一致:
- Node.js版本
- pnpm版本
- 主要依赖版本
问题2:IDE无法识别pnpm命令
现象:CMD可用,IDE终端不可用
解决步骤:
- 重启电脑(最可靠)
- 检查IDE终端是否继承系统环境变量
- 在IDE设置中手动指定pnpm路径
问题3:依赖安装失败
现象:内网安装时提示找不到包
解决:
- 检查pnpm-store是否完整传输
- 确保store-dir配置正确
- 使用
pnpm install --offline强制离线安装
📋 迁移核对清单
- [ ] pnpm版本一致
- [ ] Node.js版本一致
- [ ] 项目代码完整(含pnpm-lock.yaml)
- [ ] pnpm-store完整传输
- [ ] 内网已配置相同存储路径
- [ ] 安装后已重启电脑/IDE
- [ ] 内网安装成功
- [ ] 项目可正常启动
💡 最佳实践建议
版本管理:在项目中固定pnpm版本
// package.json { "packageManager": "pnpm@8.x.x" }- 文档记录:记录迁移时的版本信息
- 定期同步:建立定期依赖更新机制
- 备份策略:定期备份pnpm-store目录
- 开发规范:内网开发时避免添加新的外部依赖
这样即使在不同的文件路径下,也能顺利完成pnpm项目的内网迁移。