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

https://chat.deepseek.com/share/ctmwyshe15fzmnpam9

使用 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）

安装完成后，确保终端可运行 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。

九、完整迁移检查清单

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

posted @ 2026-05-25 16:10  lizhigang  阅读(177)  评论(0)    收藏  举报