尧图网站建设 
Vitest 配置完全指南从 vite.config 到 vitest.config 的优先级、合并与最佳实践【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest本篇指南以 Vitest 官方配置文档为核心系统讲解 Vitest 配置文件的选择逻辑、查找顺序、优先级规则以及configDefaults、mergeConfig、--config、VITEST环境变量等关键配置手段的底层实现。读完本文你将能够根据项目实际情况纯 Vite 应用、非 Vite 项目、多配置文件并存、配置以函数形式导出等正确搭建 Vitest 配置并学会利用仓库源码验证配置行为的真实机制。配置文件的选择策略Vitest 如何读取你的配置Vitest 基于 Vite 构建因此天然复用 Vite 的配置体系。如果你已经在使用 Vite 且存在vite.config文件Vitest 会读取它从而与 Vite 应用共享插件与 setup 配置。但测试环境与主应用往往需要不同的设置此时 Vitest 提供三种方式让测试配置与主应用配置解耦创建vitest.config.ts它拥有更高优先级会覆盖overridevite.config.ts中的全部配置——即vite.config中的所有选项都会被忽略。Vitest 支持所有常规 JS/TS 扩展名但不支持json。通过 CLI 传入--config选项例如vitest --config ./path/to/vitest.config.ts显式指定配置文件的绝对或相对路径。在vite.config.ts内利用process.env.VITEST或defineConfig的mode属性做条件配置mode在不被--mode覆盖时会被设置为test。注意与任何环境变量一样VITEST在测试中也会暴露到import.meta.env上。配置文件的查找顺序源码级验证当没有显式传入--config时Vitest 会在项目root目录下按以下顺序查找配置文件先查找vitest.config.{ts,mts,cts,js,mjs,cjs}再查找vite.config.{ts,mts,cts,js,mjs,cjs}若两者都不存在Vitest 将在无配置文件的情况下运行这一查找逻辑与源码中的定义完全一致。在 constants.ts 中配置文件名称与扩展名被显式枚举const CONFIG_NAMES: string[] [vitest.config, vite.config] const CONFIG_EXTENSIONS: string[] [.ts, .mts, .cts, .js, .mjs, .cjs] export const configFiles: string[] CONFIG_NAMES.flatMap(name CONFIG_EXTENSIONS.map(ext name ext), )而实际的查找过程在 resolveConfig.ts 的findConfigFile中实现——它严格按顺序遍历上述configFiles列表命中第一个存在的文件即返回export function findConfigFile(root: string): string | false { for (const configFile of configFiles) { const configPath resolve(root, configFile) if (existsSync(configPath)) { return configPath } } // if not found, then there is no config to find. // false will stop vite from trying to find it again return false }从源码可以推断vitest.config.*之所以能覆盖vite.config.*正是因为它在查找列表中排在前面——一旦命中vite.config.*就永远不会被读取从而表现为后者的全部选项被忽略。为配置启用类型提示test属性与 TypeScript 引用要配置 Vitest 自身需要在 Vite 配置中加入test属性。如果defineConfig是从vite本身导入的则需要在配置文件顶部添加 triple slash 指令 来引入 Vitest 的类型声明。如果你不使用 Vite则从vitest/config导入defineConfigimport { defineConfig } from vitest/config export default defineConfig({ test: { // ... 在此处指定选项。 }, })如果你已有 Vite 配置可以通过/// reference typesvitest/config /引入test的类型/// reference typesvitest/config / import { defineConfig } from vite export default defineConfig({ test: { // ... 在此处指定选项。 }, })两条路径在源码层面是等价的从 public/config.ts 可以看到mergeConfig直接 re-export 自vitedefineConfig接受的也正是ViteUserConfig类型含test扩展字段。因此无论defineConfig来自哪里最终产出的都是一个兼容 Vite 的配置对象。基于默认值扩展configDefaultsVitest 暴露了默认配置对象configDefaults方便你在其基础上展开spread并追加自定义项import { configDefaults, defineConfig } from vitest/config export default defineConfig({ test: { exclude: [...configDefaults.exclude, packages/template/*], }, })configDefaults的定义位于 defaults.ts并经过Object.freeze冻结保证不可被意外篡改。它包含了大量关键默认值了解它们有助于你判断何时需要覆盖选项默认值说明include[**/*.{test,spec}.?(c|m)[jt]s?(x)]测试文件匹配模式exclude[**/node_modules/**, **/.git/**]默认排除目录environmentnode默认运行环境globalsfalse是否注入全局 APIwatch!isCI process.stdin.isTTY !isAgent是否默认启用监听模式allowOnly!isCI是否允许.onlyclearMockstrue测试间是否自动清理 mockrestoreMocks/mockResetfalse是否自动恢复/重置 mockteardownTimeout10000teardown 超时毫秒maxConcurrency5最大并发数updatefalse是否默认更新快照reporters[default]CI/Agent 下为minimalGITHUB_ACTIONS 时追加github-actions默认报告器fakeTimers{ loopLimit: 10_000, shouldClearNativeTimers: true }假定时器默认行为typecheck.checkertsc类型检查器slowTestThreshold300慢测试阈值毫秒该默认对象在 resolveConfig.ts 中通过deepMerge({}, configDefaults, options)与用户配置合并因此你在test中未指定的选项都会自动回落到上表中的默认值。合并多个配置文件mergeConfig当使用独立的vitest.config.js时如果你仍想继承另一个配置文件例如vite.config中的 Vite 选项可以使用mergeConfig进行深度合并import { defineConfig, mergeConfig } from vitest/config import viteConfig from ./vite.config export default mergeConfig(viteConfig, defineConfig({ test: { exclude: [packages/template/*], }, }))注意此处的语义mergeConfig(viteConfig, vitestConfig)会将两个配置对象深度合并test等 Vitest 专属选项来自第二个参数而 Vite 通用选项插件、别名等来自第一个参数从而实现在复用 Vite 配置的同时覆盖测试相关选项。配置以函数形式导出时如果 Vite 配置是以函数形式导出的以便接收configEnv环境信息你可以这样组合import { defineConfig, mergeConfig } from vitest/config import viteConfig from ./vite.config export default defineConfig(configEnv mergeConfig( viteConfig(configEnv), defineConfig({ test: { exclude: [packages/template/*], }, }) ))这里viteConfig(configEnv)先被调用以生成实际配置对象再与测试配置合并确保函数形式的配置同样能够正常参与合并。mergeConfig从vite中 re-export见 public/config.ts因此其合并行为与 Vite 自身的配置合并完全一致。复用 Vite 的全部配置能力由于 Vitest 使用 Vite 配置你可以在顶层而非test属性内直接使用 Vite 的任何配置选项。例如define定义全局变量resolve.alias配置路径别名以及plugins、server、resolve等一切 Vite 支持的能力这些选项应定义在配置对象的顶层而不是嵌套在test属性内部——test属性只负责 Vitest 专属的测试选项。自动依赖安装与VITEST_SKIP_INSTALL_CHECKSVitest 在检测到某些必要依赖未安装时会提示你进行安装。如果你希望禁用这一行为可以设置环境变量VITEST_SKIP_INSTALL_CHECKS1这一机制的实现位于 packageInstaller.ts。ensureInstalled首先检查VITEST_SKIP_INSTALL_CHECKS一旦设置则直接跳过全部检查返回true随后它通过isPackageExists检测依赖是否可用若缺失则在 TTY 终端中弹出交互式确认prompts用户确认后调用antfu/install-pkg以dev: true方式安装依赖并提示安装完成请重新运行命令。若运行环境不是 TTY如 CI则不会弹出提示直接返回false。因此在 CI / 非交互环境中未安装的依赖不会被自动安装Vitest 会以 MISSING DEPENDENCY 标签提示缺失在本地交互终端中你可以选择一键安装后再重新运行。在 CI 管道中显式设置VITEST_SKIP_INSTALL_CHECKS1是一种常见的确定性做法可避免意外的交互等待。配置选项与项目Projects的限制所有配置选项的完整列表可参阅 config 目录 下的各选项页面。其中需要注意部分选项在 project 配置中不受支持文档中以 图标标记这类选项只能在根级rootVitest 配置中设置而不能在子项目project配置内覆盖。从实现角度看这一限制与配置的解析链路相关根配置会通过findConfigFile在项目 root 下被加载并通过deepMerge({}, configDefaults, options)得到完整默认值resolveConfig.ts而子项目配置只允许覆盖其中被允许的字段。涉及include、exclude等高频选项时建议先在根配置确认默认值再决定是在根级还是项目级覆盖避免出现配置不生效的困惑。实战要点速查纯 Vite 项目直接在vite.config.ts中添加test属性 /// reference typesvitest/config /与主应用共享插件。非 Vite 项目 / 需要独立测试配置创建vitest.config.ts从vitest/config导入defineConfig此时vite.config.ts会被完全忽略。同时保留两套配置在vitest.config.ts中用mergeConfig(viteConfig, defineConfig({ test: {...} }))继承 Vite 配置若 Vite 配置是函数先调用再合并。只想微调默认行为使用configDefaults.exclude等展开默认数组而非硬编码完整列表。CI 环境设置VITEST_SKIP_INSTALL_CHECKS1并配合--config显式指定配置文件保证行为可复现。条件切换在vite.config.ts中根据process.env.VITEST或mode test动态切换配置分支。配置文件查找记住顺序vitest.config.*优先于vite.config.*支持.ts/.mts/.cts/.js/.mjs/.cjs六种扩展名但不支持json。通过结合 defaults.ts、constants.ts、resolveConfig.ts 与 packageInstaller.ts 的源码你可以准确预测 Vitest 在任意目录结构下的配置文件解析结果从而为不同规模的项目设计出既清晰又不易出错的测试配置方案。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vitest 配置完全指南：从 vite.config 到 vitest.config 的优先级、合并与最佳实践
Vitest 配置完全指南从 vite.config 到 vitest.config 的优先级、合并与最佳实践【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest本篇指南以 Vitest 官方配置文档为核心系统讲解 Vitest 配置文件的选择逻辑、查找顺序、优先级规则以及configDefaults、mergeConfig、--config、VITEST环境变量等关键配置手段的底层实现。读完本文你将能够根据项目实际情况纯 Vite 应用、非 Vite 项目、多配置文件并存、配置以函数形式导出等正确搭建 Vitest 配置并学会利用仓库源码验证配置行为的真实机制。配置文件的选择策略Vitest 如何读取你的配置Vitest 基于 Vite 构建因此天然复用 Vite 的配置体系。如果你已经在使用 Vite 且存在vite.config文件Vitest 会读取它从而与 Vite 应用共享插件与 setup 配置。但测试环境与主应用往往需要不同的设置此时 Vitest 提供三种方式让测试配置与主应用配置解耦创建vitest.config.ts它拥有更高优先级会覆盖overridevite.config.ts中的全部配置——即vite.config中的所有选项都会被忽略。Vitest 支持所有常规 JS/TS 扩展名但不支持json。通过 CLI 传入--config选项例如vitest --config ./path/to/vitest.config.ts显式指定配置文件的绝对或相对路径。在vite.config.ts内利用process.env.VITEST或defineConfig的mode属性做条件配置mode在不被--mode覆盖时会被设置为test。注意与任何环境变量一样VITEST在测试中也会暴露到import.meta.env上。配置文件的查找顺序源码级验证当没有显式传入--config时Vitest 会在项目root目录下按以下顺序查找配置文件先查找vitest.config.{ts,mts,cts,js,mjs,cjs}再查找vite.config.{ts,mts,cts,js,mjs,cjs}若两者都不存在Vitest 将在无配置文件的情况下运行这一查找逻辑与源码中的定义完全一致。在 constants.ts 中配置文件名称与扩展名被显式枚举const CONFIG_NAMES: string[] [vitest.config, vite.config] const CONFIG_EXTENSIONS: string[] [.ts, .mts, .cts, .js, .mjs, .cjs] export const configFiles: string[] CONFIG_NAMES.flatMap(name CONFIG_EXTENSIONS.map(ext name ext), )而实际的查找过程在 resolveConfig.ts 的findConfigFile中实现——它严格按顺序遍历上述configFiles列表命中第一个存在的文件即返回export function findConfigFile(root: string): string | false { for (const configFile of configFiles) { const configPath resolve(root, configFile) if (existsSync(configPath)) { return configPath } } // if not found, then there is no config to find. // false will stop vite from trying to find it again return false }从源码可以推断vitest.config.*之所以能覆盖vite.config.*正是因为它在查找列表中排在前面——一旦命中vite.config.*就永远不会被读取从而表现为后者的全部选项被忽略。为配置启用类型提示test属性与 TypeScript 引用要配置 Vitest 自身需要在 Vite 配置中加入test属性。如果defineConfig是从vite本身导入的则需要在配置文件顶部添加 triple slash 指令 来引入 Vitest 的类型声明。如果你不使用 Vite则从vitest/config导入defineConfigimport { defineConfig } from vitest/config export default defineConfig({ test: { // ... 在此处指定选项。 }, })如果你已有 Vite 配置可以通过/// reference typesvitest/config /引入test的类型/// reference typesvitest/config / import { defineConfig } from vite export default defineConfig({ test: { // ... 在此处指定选项。 }, })两条路径在源码层面是等价的从 public/config.ts 可以看到mergeConfig直接 re-export 自vitedefineConfig接受的也正是ViteUserConfig类型含test扩展字段。因此无论defineConfig来自哪里最终产出的都是一个兼容 Vite 的配置对象。基于默认值扩展configDefaultsVitest 暴露了默认配置对象configDefaults方便你在其基础上展开spread并追加自定义项import { configDefaults, defineConfig } from vitest/config export default defineConfig({ test: { exclude: [...configDefaults.exclude, packages/template/*], }, })configDefaults的定义位于 defaults.ts并经过Object.freeze冻结保证不可被意外篡改。它包含了大量关键默认值了解它们有助于你判断何时需要覆盖选项默认值说明include[**/*.{test,spec}.?(c|m)[jt]s?(x)]测试文件匹配模式exclude[**/node_modules/**, **/.git/**]默认排除目录environmentnode默认运行环境globalsfalse是否注入全局 APIwatch!isCI process.stdin.isTTY !isAgent是否默认启用监听模式allowOnly!isCI是否允许.onlyclearMockstrue测试间是否自动清理 mockrestoreMocks/mockResetfalse是否自动恢复/重置 mockteardownTimeout10000teardown 超时毫秒maxConcurrency5最大并发数updatefalse是否默认更新快照reporters[default]CI/Agent 下为minimalGITHUB_ACTIONS 时追加github-actions默认报告器fakeTimers{ loopLimit: 10_000, shouldClearNativeTimers: true }假定时器默认行为typecheck.checkertsc类型检查器slowTestThreshold300慢测试阈值毫秒该默认对象在 resolveConfig.ts 中通过deepMerge({}, configDefaults, options)与用户配置合并因此你在test中未指定的选项都会自动回落到上表中的默认值。合并多个配置文件mergeConfig当使用独立的vitest.config.js时如果你仍想继承另一个配置文件例如vite.config中的 Vite 选项可以使用mergeConfig进行深度合并import { defineConfig, mergeConfig } from vitest/config import viteConfig from ./vite.config export default mergeConfig(viteConfig, defineConfig({ test: { exclude: [packages/template/*], }, }))注意此处的语义mergeConfig(viteConfig, vitestConfig)会将两个配置对象深度合并test等 Vitest 专属选项来自第二个参数而 Vite 通用选项插件、别名等来自第一个参数从而实现在复用 Vite 配置的同时覆盖测试相关选项。配置以函数形式导出时如果 Vite 配置是以函数形式导出的以便接收configEnv环境信息你可以这样组合import { defineConfig, mergeConfig } from vitest/config import viteConfig from ./vite.config export default defineConfig(configEnv mergeConfig( viteConfig(configEnv), defineConfig({ test: { exclude: [packages/template/*], }, }) ))这里viteConfig(configEnv)先被调用以生成实际配置对象再与测试配置合并确保函数形式的配置同样能够正常参与合并。mergeConfig从vite中 re-export见 public/config.ts因此其合并行为与 Vite 自身的配置合并完全一致。复用 Vite 的全部配置能力由于 Vitest 使用 Vite 配置你可以在顶层而非test属性内直接使用 Vite 的任何配置选项。例如define定义全局变量resolve.alias配置路径别名以及plugins、server、resolve等一切 Vite 支持的能力这些选项应定义在配置对象的顶层而不是嵌套在test属性内部——test属性只负责 Vitest 专属的测试选项。自动依赖安装与VITEST_SKIP_INSTALL_CHECKSVitest 在检测到某些必要依赖未安装时会提示你进行安装。如果你希望禁用这一行为可以设置环境变量VITEST_SKIP_INSTALL_CHECKS1这一机制的实现位于 packageInstaller.ts。ensureInstalled首先检查VITEST_SKIP_INSTALL_CHECKS一旦设置则直接跳过全部检查返回true随后它通过isPackageExists检测依赖是否可用若缺失则在 TTY 终端中弹出交互式确认prompts用户确认后调用antfu/install-pkg以dev: true方式安装依赖并提示安装完成请重新运行命令。若运行环境不是 TTY如 CI则不会弹出提示直接返回false。因此在 CI / 非交互环境中未安装的依赖不会被自动安装Vitest 会以 MISSING DEPENDENCY 标签提示缺失在本地交互终端中你可以选择一键安装后再重新运行。在 CI 管道中显式设置VITEST_SKIP_INSTALL_CHECKS1是一种常见的确定性做法可避免意外的交互等待。配置选项与项目Projects的限制所有配置选项的完整列表可参阅 config 目录 下的各选项页面。其中需要注意部分选项在 project 配置中不受支持文档中以 图标标记这类选项只能在根级rootVitest 配置中设置而不能在子项目project配置内覆盖。从实现角度看这一限制与配置的解析链路相关根配置会通过findConfigFile在项目 root 下被加载并通过deepMerge({}, configDefaults, options)得到完整默认值resolveConfig.ts而子项目配置只允许覆盖其中被允许的字段。涉及include、exclude等高频选项时建议先在根配置确认默认值再决定是在根级还是项目级覆盖避免出现配置不生效的困惑。实战要点速查纯 Vite 项目直接在vite.config.ts中添加test属性 /// reference typesvitest/config /与主应用共享插件。非 Vite 项目 / 需要独立测试配置创建vitest.config.ts从vitest/config导入defineConfig此时vite.config.ts会被完全忽略。同时保留两套配置在vitest.config.ts中用mergeConfig(viteConfig, defineConfig({ test: {...} }))继承 Vite 配置若 Vite 配置是函数先调用再合并。只想微调默认行为使用configDefaults.exclude等展开默认数组而非硬编码完整列表。CI 环境设置VITEST_SKIP_INSTALL_CHECKS1并配合--config显式指定配置文件保证行为可复现。条件切换在vite.config.ts中根据process.env.VITEST或mode test动态切换配置分支。配置文件查找记住顺序vitest.config.*优先于vite.config.*支持.ts/.mts/.cts/.js/.mjs/.cjs六种扩展名但不支持json。通过结合 defaults.ts、constants.ts、resolveConfig.ts 与 packageInstaller.ts 的源码你可以准确预测 Vitest 在任意目录结构下的配置文件解析结果从而为不同规模的项目设计出既清晰又不易出错的测试配置方案。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考