使用 Vue 官方脚手架创建项目时遇到 Node 18 报错问题的排查与解决

我在使用vue官方脚手架创建vue工程时，按照官网要求使用node18，但创建的项目无法启动，下面介绍我是如何一步一步的分析问题和解决的。

创建项目

创建项目的文档在这，官方推荐使用node 18或者更新的版本。

我使用的是 Node 18.20.8，环境如下：

shell 复制代码

$ nvm list

    24.3.0
    22.17.0
    20.19.3
  * 18.20.8 (Currently using 64-bit executable)
    16.20.2

PNPM 版本为：

shell 复制代码

$ pnpm -v
10.12.4

安装依赖

执行 pnpm install 后没有报错：

shell 复制代码

$ pnpm install
Packages: +417
...
 WARN  Issues with peer dependencies found
...
Done in 3m 15.4s using pnpm v10.12.4

项目启动失败

运行时和编译时报错：

vbnet 复制代码

TypeError: crypto.hash is not a function

完整堆栈信息如下：

shell 复制代码

$ pnpm run dev

> vite-vue3-ts-template-new@0.0.0 dev D:\chenbitao\Developer\github\vite-vue3-ts-template-new
> vite

error when starting dev server:
TypeError: crypto.hash is not a function
    at getHash (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:2834:21)
    at getLockfileHash (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:11716:9)
    at getDepHash (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:11719:23)
    at initDepsOptimizerMetadata (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:11180:53)
    at createDepsOptimizer (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:34593:17)
    at new DevEnvironment (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:35357:109)
    at Object.defaultCreateClientDevEnvironment [as createEnvironment] (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:35776:9)
    at _createServer (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/chunks/dep-Bsx9IwL8.js:28359:132)
    at async CAC.<anonymous> (file:///D:/chenbitao/Developer/github/vite-vue3-ts-template-new/node_modules/.pnpm/vite@7.0.0_@types+node@22.16.0_jiti@2.4.2/node_modules/vite/dist/node/cli.js:573:18)
 ELIFECYCLE  Command failed with exit code 1.

排查过程

报错原因是TypeError: crypto.hash is not a function,通过查看代码，找到node:crypto的文档。

注释显示在20.12.0才被添加进来，21.7.0是内部版本，不用管它（node只发行偶数版本）

node 18的文档中确实没有hash方法。再检查node 20文档，发现了方法的定义。

解决方式

找到问题，尝试去解决，使用nvm use 20来使用node20版本。可以使用nvm install 20来安装node 20，如果没有安装过node 20版本，会安装node20的最新版本。

bash 复制代码

nvm use 20
rm -rf node_modules pnpm-lock.yarm
pnpm install

新问题

安装完成后又有了新的错误

shell 复制代码

$ pnpm run dev

> vite-vue3-ts-template-new@0.0.0 dev D:\chenbitao\Developer\github\vite-vue3-ts-template-new
> vite

failed to load config from D:\chenbitao\Developer\github\vite-vue3-ts-template-new\vite.config.ts
error when starting dev server:
Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'D:\chenbitao\Developer\github\vite-vue3-ts-template-new\node_modules\.pnpm\@vitejs+plugin-vue-jsx@5.0._6c34f5667c9e04ebf9442bf5fdf07175\node_modules\@rolldown\pluginutils\dist\esm\index.js' imported from D:\chenbitao\Developer\github\vite-vue3-ts-template-new\node_modules\.pnpm\@vitejs+plugin-vue-jsx@5.0._6c34f5667c9e04ebf9442bf5fdf07175\node_modules\@vitejs\plugin-vue-jsx\dist\index.mjs
    at finalizeResolution (node:internal/modules/esm/resolve:283:11)
    at moduleResolve (node:internal/modules/esm/resolve:952:10)
    at defaultResolve (node:internal/modules/esm/resolve:1188:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:642:12)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:591:25)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:574:38)
    at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:236:38)
    at ModuleJob._link (node:internal/modules/esm/module_job:130:49)
 ELIFECYCLE  Command failed with exit code 1.

原因分析

检查node_modules中的依赖，发现引入的文件内容是空的，没有\dist\esm\index.js

这个问题刚好之前解决过，可以查看这篇文档# 使用 force-resolutions 强制锁定 npm/yarn 依赖版本

因为这里我使用的是pnpm，所以按照pnpm的方法来解决。

makefile 复制代码

# pnpm-workspace.yaml
overrides:
  "@rolldown/pluginutils": "1.0.0-beta.23"

再次执行pnpm install

最终验证

文件已经拉取下来了，再次执行pnpm run dev，一切正常，其他的命令也都正常了。

总结

Node 18 不支持 crypto.hash() ，导致 Vite 启动失败。
升级至 Node 20 可以解决此问题。
由于某些依赖缺失或版本不兼容，使用 pnpm.overrides 手动指定依赖版本解决问题。
建议使用 最新稳定版 Node LTS + 最新依赖组合，并注意模块兼容性。