处理 nitro 插件在 github workflow 出现的故障

在本地、 github workflow 和 cloudflare worker 流水线这三个环境内，运行 apps\admin\package.json 的 build 、vite:build:prod:cloudflare 和 vite:build:prod:github 命令，都会出现以下报错。

阅读以下错误日志，并修复错误。

◐ Building [Client]                                                            nitro 13:42:44
vite v7.1.12 building for production...
╭─────────────────────────────────────────────╮
│ 您好! 欢迎使用 pure-admin 开源项目          │
│ 我们为您精心准备了下面两个贴心的保姆级文档  │
│ https://pure-admin.cn                       │
│ https://pure-admin-utils.netlify.app        │
╰─────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────╮
│ 🎉 恭喜打包完成（总用时00分00秒，打包后的大小为15.09 MB）  │
╰────────────────────────────────────────────────────────────╯
mk ./types/components-in-components-path.d.ts success

[plugin vite:resolve] Module "node:path" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/@ruan-cat+utils@4.18.0_asyn_eb8b6534a56ee78f33261f5b71752370/node_modules/@ruan-cat/utils/dist/index.js". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:fs" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/@ruan-cat+utils@4.18.0_asyn_eb8b6534a56ee78f33261f5b71752370/node_modules/@ruan-cat/utils/dist/index.js". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:path" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/@ruan-cat+utils@4.18.0_asyn_eb8b6534a56ee78f33261f5b71752370/node_modules/@ruan-cat/utils/src/monorepo.ts". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:fs" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/@ruan-cat+utils@4.18.0_asyn_eb8b6534a56ee78f33261f5b71752370/node_modules/@ruan-cat/utils/src/monorepo.ts". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:fs" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/tinyglobby@0.2.15/node_modules/tinyglobby/dist/index.mjs". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:path" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/tinyglobby@0.2.15/node_modules/tinyglobby/dist/index.mjs". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:url" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/tinyglobby@0.2.15/node_modules/tinyglobby/dist/index.mjs". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:module" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/fdir@6.5.0_picomatch@4.0.3/node_modules/fdir/dist/index.mjs". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:path" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/fdir@6.5.0_picomatch@4.0.3/node_modules/fdir/dist/index.mjs". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
[plugin vite:resolve] Module "node:fs" has been externalized for browser compatibility, imported by "D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/fdir@6.5.0_picomatch@4.0.3/node_modules/fdir/dist/index.mjs". See https://vite.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details.
✓ 6656 modules transformed.
✗ Build failed in 33.87s
error during build:
../../node_modules/.pnpm/fdir@6.5.0_picomatch@4.0.3/node_modules/fdir/dist/index.mjs (1:9): "createRequire" is not exported by "__vite-browser-external", imported by "../../node_modules/.pnpm/fdir@6.5.0_picomatch@4.0.3/node_modules/fdir/dist/index.mjs".
file: D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/fdir@6.5.0_picomatch@4.0.3/node_modules/fdir/dist/index.mjs:1:9

1: import { createRequire } from "module";
            ^
2: import { basename, dirname, normalize, relative, resolve, sep } from "path";
3: import * as nativeFs from "fs";

    at getRollupError (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/parseAst.js:401:41)
    at error (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/parseAst.js:397:42)
    at Module.error (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:16956:16)
    at Module.traceVariable (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:17412:29)
    at ModuleScope.findVariable (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:15076:39)
    at Identifier.bind (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:5423:40)
    at CallExpression.bind (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:2813:23)
    at CallExpression.bind (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:12123:15)
    at VariableDeclarator.bind (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:2813:23)
    at VariableDeclaration.bind (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:2809:28)
    at Program.bind (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:2809:28)
    at Module.bindReferences (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:16935:18)
    at Graph.sortModules (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:22746:20)
    at Graph.build (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:22644:14)
    at async file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:23335:13
    at async catchUnfinishedHookActions (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:22805:16)
    at async rollupInternal (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/rollup@4.53.3/node_modules/rollup/dist/es/shared/node-entry.js:23330:5)
    at async buildEnvironment (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/vite@7.1.12_@types+node@24._3fdb25a548868c1edd81e3462ec52546/node_modules/vite/dist/node/chunks/config.js:33771:12)
    at async Object.build (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/vite@7.1.12_@types+node@24._3fdb25a548868c1edd81e3462ec52546/node_modules/vite/dist/node/chunks/config.js:34129:19)
    at async buildEnvironments (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/nitro@3.0.1-alpha.1_@vercel_b41fba7e78e056adfc11b8630bfbe598/node_modules/nitro/dist/_build/vite.plugin.mjs:156:3)
    at async Object.buildApp (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/vite@7.1.12_@types+node@24._3fdb25a548868c1edd81e3462ec52546/node_modules/vite/dist/node/chunks/config.js:34123:5)
    at async CAC.<anonymous> (file:///D:/code/github-desktop-store/01s-11comm/node_modules/.pnpm/vite@7.1.12_@types+node@24._3fdb25a548868c1edd81e3462ec52546/node_modules/vite/dist/node/cli.js:629:3)
 ELIFECYCLE  Command failed with exit code 1.

1. 请你对比当前的 git 提交信息，重点对比阅读 🔧 config(prompt,config,admin)!: 配置 nitro 部署到 cloudflare worker 内 ，即 Commit: 2c41183cb68d9a6ca393fc82d6d4b4dfd290d1ec 的提交。对比现在的内容个和 main 分支内容的差异。仔细研究一下，为什么 main 分支的构建行为是成功的？

05 解决方案

问题根源：@ruan-cat/utils 版本 4.18.0 引入了 Node.js 特定的代码（使用了 node:path、node:fs 等模块），这些代码在 Nitro 进行客户端构建时被错误地包含，导致 Vite 将这些模块外部化为 __vite-browser-external，从而引发 createRequire is not exported 错误。

修复方法：将 @ruan-cat/utils 版本从 ^4.16.0（实际安装了 4.18.0）锁定到 4.16.0。

具体步骤：

1. 在 apps/admin/package.json 中，将 "@ruan-cat/utils": "^4.16.0" 修改为 "@ruan-cat/utils": "4.16.0"
2. 运行 pnpm install 重新安装依赖
3. 运行 pnpm vite:build:prod 验证构建成功

关键发现：

• main 分支和 dev 分支都受到此问题影响，说明这是一个系统性问题
• 问题不在于 Vite、Nitro 或 pnpm-workspace.yaml 的 overrides 配置
• 问题出在依赖版本漂移：^4.16.0 允许安装 4.18.0，而 4.18.0 包含了不兼容的代码

预防措施：对于包含 Node.js 特定代码的核心依赖，应该使用精确版本号而不是语义化版本范围。

01 回答问题

当前错误：fdir/dist/index.mjs 里 import { createRequire } from "module"，Vite/rollup 将 module 替成 __vite-browser-external（不导出 createRequire）导致构建失败。错误只在 GitHub Workflow 跑 pnpm run build（即 turbo → @01s-11comm/admin#vite:build:prod）时出现。
工程现状：apps/admin Vite 配置启用了 nitro() 插件，nitro.config.ts 设为 preset: "cloudflare_module" 且 nodeCompat: true。仓库内没有 pnpm-lock.yaml，rg 没找到任何对 fdir 的源码引用，说明它来自某个未锁定的三方依赖。
CI 流程：.github/workflows/ci.yaml 在 Ubuntu 上用 Node 22.14.0、全量递归安装，再跑 pnpm run ci → pnpm run build → turbo。Cloudflare worker 流水线的具体安装/构建命令暂未知。
为避免瞎改，我需要确认几件事：

1. 允许你在本地装依赖并运行 pnpm why fdir、pnpm -F @01s-11comm/admin vite:build:prod 复现/定位。
2. Cloudflare worker 流水线用的确切命令是 vite:build:prod 。
3. 不新增 pnpm-lock.yaml 来锁定依赖版本。
4. nitro 全栈构建必须在每次 CI 的 web 前端构建里运行。
5. 不强制要求保留 nodeCompat: true / cloudflare_module 这一 preset？（关系到是否可以通过 external/stub 方式规避 fdir 依赖）

确认后我会按需执行：定位 fdir 的引入链 → 给出最小改动（如锁版本、external/stub、或按环境开关 nitro）→ 调整配置并跑 pnpm -F @01s-11comm/admin typecheck。

另外，我需要你制作可以在命令行内传递 nitro preset 的命令。制作两个命令，一个是传递 cloudflare_module 的，另一个是传递默认预设的。

具体可以参考文档 https://v3.nitro.build/ 。

02 升级依赖

请问我是否可以通过升级 vite tinyglobby fdir 等依赖，升级到最新版，以便解决该故障？我不太喜欢这种依赖包 overrides 的处理方案。

03 工作收尾

很好。

1. 请你暂存 git 工作区，生成一个中文说明的 git commit，说明清楚你的改动。
2. 将分支合并到 dev 分支内。
3. 删除掉你刚才新创建的本地验证分支 chore/vite-upgrade-validation 。
4. 将你的修改方式，和验证方式，总结成可以复用的经验。编写成报告供我复盘总结。

04 消除 peer warning

1. 请你帮我消除 peer warning 信息。
2. 去 pnpm-workspace.yaml 内补全对等 peer 依赖清单。
3. 安装依赖，并检查日志是否出现对等依赖缺失的信息。

05 尝试不使用 overrides 配置

1. 根据报告 apps\admin\src\docs\reports\2025-12-09-nitro-build-ruan-cat-utils-version-fix.md 所述，既然是 @ruan-cat/utils 的故障，我现在已经修复了 @ruan-cat/utils 的故障，并且刚才更新了依赖，请你帮我改成不使用 overrides 的方案。
2. 在 pnpm-workspace.yaml 内，不对特定依赖做覆盖。
3. 升级这些被覆盖依赖的版本，升级到最新版本。
4. 运行 apps\admin\package.json 的 vite:build:prod:cloudflare 和 vite:build:prod:github 命令，检查是否还会出现 apps\admin\src\docs\prompts\各种杂项\fix-nitro-build-in-github-error.md 报告第一段落所述的问题。

贡献者

ruan-cat

页面历史

最后编辑于 2 分钟前

查看完整历史

c5fdbc6-📃 docs(claude): 增加【openspec 使用规范】