第三方包在应用里正常但在 Vitest 中加载失败如何通过 server.deps.inline 解决【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest你遇到的问题是同一个第三方包在应用构建里运行正常但在 Vitest 中 import 时报错测试无法启动。这类错误的根源是 Vitest 对依赖的加载方式与应用构建不同——Vitest 默认把node_modules下的依赖外部化由 Node.js 直接加载此时 Node 的 ESM 与 package 规则生效而那些只能在打包器重写或解析之后才合法的包就会加载失败。解决办法是在 Vitest 配置 中通过test.server.deps.inline让 Vite 接管该依赖的转换与解析而不是交给 Node.js。先确认错误属于这一类以下报错是文档中列出的典型现象。如果你看到的是这些错误之一且包在应用里能正常运行就适用本文的排查路径来源docs/guide/common-errors.mdCannot find module ./relative-path imported from ...Unexpected token exportCannot use import statement outside a moduleModule ... seems to be an ES Module but shipped in a CommonJS package.Unknown file extension .css常见的包特征包括在.js文件里使用 ESM 语法但package.json没有type: moduleESM 文件中使用无扩展名的相对导入exports、imports、main或module字段配置不正确CommonJS 与 ESM 入口混用只有经过打包才能工作import 了 CSS 或其他非 JavaScript 文件且预期由打包器处理优先尝试在包层面修复文档建议能修包就先修包让 Node.js 可以直接加载。具体做法包括为 ESM 的.js文件添加type: module、改用.mjs、在 ESM 导入中写明文件扩展名、确保exports指向 Node.js 可加载的文件。这一步适用于你能修改或向上游修复的场景如果包无法修改才走下面的server.deps.inline方案。配置 server.deps.inline 让 Vite 接管依赖server.deps.inline的类型是(string | RegExp)[] | true默认值为“所有未被外部化的模块”。列入该列表的模块会由 Vite 转换和解析并运行在 Vite 的 module runner 中从而绕过 Node.js 的直接加载规则。关键点是要内联整条通向问题包的依赖链。如果你的源码 import 了wrapper-package而wrapper-package又 import 了出问题的broken-package两个包都要写进inlineimport { defineConfig } from vitest/config export default defineConfig({ test: { server: { deps: { inline: [wrapper-package, broken-package], }, }, }, })配置写在 Vitest 配置文件如vitest.config.js/vitest.config.ts的test.server.deps.inline下保存后重新运行测试即可生效。包名如何匹配文件路径字符串条目不是按名字直接比较而是先做规范化再与完整文件路径匹配来源docs/config/server.md提供字符串时会先加上/node_modules/或其他deps.moduleDirectories段前缀例如react变成/node_modules/react/然后再与完整文件路径匹配提供RegExp时直接与完整文件路径匹配。对 monorepo 中自研的包要注意如果包company/some-name位于packages/some-name应在inline中写some-name同时把packages加入deps.moduleDirectories。由于设置deps.moduleDirectories会覆盖默认值[node_modules]仍需保留node_modules来源docs/config/deps.mdimport { defineConfig } from vitest/config export default defineConfig({ test: { deps: { moduleDirectories: [node_modules, packages], }, server: { deps: { inline: [some-name], }, }, }, })关于 server 选项的两点说明文档将server标记为废弃选项在 Vitest 4 之前它用于配置vite-node服务器目前它用于配置内联/外部化机制以及 module runner 的调试配置本文的用法仍在其当前职责范围内。文档明确警告内联/外部化选项只应作为最后手段使用例如为了修复问题而内联非法的外部依赖即本场景或为了性能而外部化被自动内联的依赖。正常情况下 Vitest 应当自动处理。替代写法ssr.resolve.noExternal如果该依赖在 SSR 构建中也需要被 Vite 打包可以改用 Vite 的ssr.resolve.noExternal。Vitest 会把ssr.resolve.noExternal合并进server.deps.inline两者效果相同import { defineConfig } from vitest/config export default defineConfig({ ssr: { resolve: { noExternal: [wrapper-package, broken-package], }, }, })验证与限制配置完成后重新运行测试确认之前出现的加载报错上文列出的错误信息不再出现测试可以正常执行即为配置生效。需要注意的边界不要把无法修改的包之外的健康依赖也塞进inline文档的定位是“最后手段”只针对确实无法被 Node.js 直接加载的依赖。方向相反的操作是server.deps.external它指定不应被 Vite 转换、由引擎直接处理的模块默认即moduleDirectories内的文件。外部化模块不在 module graph 中其变化不会触发测试重启。性能调优时才需要关注它与本故障排查无关。如果你的报错其实属于 CJS 命名导出不被静态分析、或require()语义问题那对应的是deps.interopDefault、experimental.viteModuleRunner等别的配置不属于server.deps.inline的适用范围。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考