使用 pnpm 构建 Vue2 项目操作总结（Node 16 → Node 22）

本指南适用于从 npm + Node.js 16 迁移到 pnpm + Node.js 22 的开发环境。核心流程：先切到 Node 16，从原有 package-lock.json 提取 canvg、jquery、jsbarcode、jspdf、socket.io-client、request 等依赖的精确版本，更新 package.json；再切回 Node 22，用 pnpm 安装依赖并启动开发服务器。

一、准备工作

1.1 确认当前项目结构

项目根目录下存在 package.json 和 package-lock.json（npm 原始 lock 文件）
项目使用的构建工具为 vue-cli-service（Vue CLI）

1.2 安装 Node.js 版本管理工具（推荐 nvm）

Windows：使用 nvm-windows
macOS/Linux：使用 nvm

安装完成后，确保终端可运行 nvm 命令。

二、从 `package-lock.json` 提取精确依赖版本

2.1 切换到 Node.js 16

nvm install 16
nvm use 16
node -v   # 应显示 v16.x.x

2.2 查找目标依赖的实际安装版本

在原有 npm 环境中执行：

npm list canvg jquery jsbarcode jspdf socket.io-client request --depth=0

或者直接打开 package-lock.json，搜索以下包名并记录 version 字段：

包名	示例版本（请以实际为准）
canvg	3.0.11
jquery	3.7.1
jsbarcode	3.12.3
jspdf	2.5.2
socket.io-client	4.8.3
request	2.88.2

2.3 将精确版本写入 `package.json`

打开项目的 package.json，在 dependencies 或 devDependencies 中添加（根据原项目归属）：

"dependencies": {
  "canvg": "3.0.11",
  "jquery": "3.7.1",
  "jsbarcode": "3.12.3",
  "jspdf": "2.5.2",
  "socket.io-client": "4.8.3",
  "request": "2.88.2"
}

注意：request 已废弃但项目仍依赖，保留原版本即可。

2.4 清理冲突或无用依赖（可选）

若 package.json 中包含 @dhtmlx/trial-vue-gantt 等要求 Vue 3 的包且项目实际未使用，建议删除，避免后续兼容问题。

保存 package.json。

三、切换到 Node.js 22 并安装 pnpm

3.1 使用 Node.js 22

nvm install 22
nvm use 22
node -v   # 应显示 v22.x.x

3.2 全局安装 pnpm

npm install -g pnpm

Windows PowerShell 权限问题处理（如报错 “无法加载 pnpm.ps1”）：
以管理员身份运行 PowerShell，执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

验证安装：

pnpm -v

四、使用 pnpm 安装依赖

4.1 执行安装

进入项目根目录，删除旧的 node_modules 和 package-lock.json（可选但建议）：

rm -rf node_modules package-lock.json

然后执行：

pnpm install

首次安装会自动生成 pnpm-lock.yaml，并可能提示部分依赖的构建脚本被忽略（如 core-js、highlight.js、yorkie）。

4.2 处理被忽略的构建脚本

若出现类似以下提示：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: core-js@3.49.0, highlight.js@9.18.5, yorkie@2.0.0

需要批准这些包运行必要的安装脚本（例如 yorkie 用于 Git hooks）。

方法一（推荐）：交互式批准

pnpm approve-builds

使用键盘方向键移动光标
按空格键选中需要构建的包：core-js、yorkie（highlight.js 可选）
按回车确认，等待脚本执行完毕

方法二：手动重建特定包

pnpm rebuild core-js yorkie

完成此步骤后，后续 pnpm install 或 pnpm run dev 不再报 ERR_PNPM_IGNORED_BUILDS 错误。

五、配置项目以兼容 Node.js 22

5.1 安装 cross-env（跨平台环境变量工具）

pnpm add -D cross-env

5.2 修改 `package.json` 中的 scripts

为 vue-cli-service 相关命令添加 cross-env NODE_OPTIONS=--openssl-legacy-provider，解决 Node.js 22 中 OpenSSL 及 http_parser 兼容问题。

修改后的示例：

"scripts": {
  "dev": "cross-env NODE_OPTIONS=--openssl-legacy-provider vue-cli-service serve",
  "build:prod": "cross-env NODE_OPTIONS=--openssl-legacy-provider vue-cli-service build",
  "build:stage": "cross-env NODE_OPTIONS=--openssl-legacy-provider vue-cli-service build --mode staging",
  "preview": "cross-env NODE_OPTIONS=--openssl-legacy-provider node build/index.js --preview",
  "lint": "eslint --ext .js,.vue src"
}

5.3 配置 Webpack 转译现代语法依赖（如遇 `Module parse failed` 错误）

若启动时报错：

Module parse failed: Unexpected token (xx:xx)
File was processed with these loaders:
...
You may need an additional loader to handle the result of these loaders.

通常来自 iobuffer 或 fast-png 等包使用了类字段语法。在项目根目录的 vue.config.js 中添加：

module.exports = {
  // ... 原有配置
  transpileDependencies: ['iobuffer', 'fast-png']
}

5.4 可选：启用 `shamefully-hoist`（兼容非标准模块引用）

若 vue-plugin-hiprint 等插件使用非标准的 require('canvg') 方式引用依赖，在 pnpm 默认严格隔离结构下可能找不到模块。可在项目根目录创建 .npmrc 文件：

shamefully-hoist=true

然后删除 node_modules 和 pnpm-lock.yaml，重新执行 pnpm install。此选项会模拟 npm 扁平化结构，将依赖提升到顶层 node_modules。

六、启动开发服务器

6.1 执行启动命令

pnpm run dev

等待编译完成，控制台输出类似：

App running at:
- Local:   http://localhost:81/
- Network: http://10.204.52.41:81/

6.2 浏览器访问

打开上述地址，验证项目是否正常运行。

七、常见问题与解决方法

错误现象	可能原因	解决方法
`cross-env` 不是内部或外部命令	cross-env 未安装或未正确链接	重新执行 `pnpm add -D cross-env`
`No such module: http_parser`	Node.js 22 默认使用 OpenSSL 3.0，与旧版模块不兼容	确保 `dev` 脚本已添加 `cross-env NODE_OPTIONS=--openssl-legacy-provider`
`Module parse failed: Unexpected token`	某些依赖使用了现代语法（类字段等），Webpack 4 默认不转译 node_modules	在 `vue.config.js` 中添加 `transpileDependencies: ['iobuffer', 'fast-png']`（根据报错包名调整）
`ERR_PNPM_IGNORED_BUILDS`	pnpm 出于安全考虑忽略部分构建脚本	运行 `pnpm approve-builds` 并选中 `core-js`, `yorkie`
模块找不到 `canvg` / `jquery` 等	pnpm 严格隔离导致插件无法解析依赖	启用 `shamefully-hoist=true`，删除 node_modules 重装
启动后页面空白或接口报错	代理配置、环境变量与包管理器无关	检查 `.env.development`、`vue.config.js` 中的 devServer 代理设置
`pnpm install` 卡住不动	网络问题或仓库源速度慢	配置 pnpm 镜像源：`pnpm config set registry https://registry.npmmirror.com`

八、生产构建与注意事项

生产构建：使用 pnpm run build:prod 或 pnpm run build:stage（根据项目配置）。
CI/CD 环境：若流水线使用 Node.js 22 + pnpm，需在流水线脚本中同样设置 NODE_OPTIONS=--openssl-legacy-provider。
废弃包警告：request、vue@2 等警告不影响运行，可暂不处理，待后续重构。
团队协作：提交 pnpm-lock.yaml 到代码仓库，确保所有成员使用相同版本。在 README.md 中注明现已迁移到 pnpm，安装步骤为 pnpm install。

九、完整迁移检查清单

使用 Node 16 从 package-lock.json 提取了 6 个依赖的精确版本
更新 package.json，添加上述依赖及精确版本号
切换到 Node 22，全局安装 pnpm
删除旧 node_modules 和 package-lock.json，执行 pnpm install
运行 pnpm approve-builds 批准 core-js 和 yorkie 构建脚本
安装 cross-env 并修改 package.json 中的 scripts
（如遇报错）在 vue.config.js 中添加 transpileDependencies
（如遇模块找不到）创建 .npmrc 并设置 shamefully-hoist=true
执行 pnpm run dev，确认开发服务器正常启动
功能回归测试（打印、条形码、Socket.IO 连接等）

文档版本：1.0
最后更新：2026-05-25
适用环境：Windows / macOS / Linux，Node.js 22 + pnpm 8+

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园 - lizhigang