Vitest 项目命名指南：深入解析 `name` 配置项、自动命名规则与 CLI/UI 颜色标识

Vitest 项目命名指南：深入解析name配置项、自动命名规则与 CLI/UI 颜色标识

【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest

name是 Vitest 中为测试项目（Test Project）或整个 Vitest 进程指定自定义名称的配置项，其值会显示在 CLI 终端与 UI 界面中，并可通过 Node.js API 的project.name访问。在多项目（projects）工作区场景下，它是在终端中快速区分不同测试项目最直接的手段；配合可选的color属性，还能为每个项目赋予独特的视觉标识。阅读本文后，你将掌握name的字符串与对象两种写法、八种可用颜色、自动命名回退规则、浏览器实例的继承命名约定，以及底层源码中的解析与重名校验逻辑。

类型定义与基本用法

name的完整类型定义如下（来自 配置文档 与源码类型声明）：

interface UserConfig { name?: string | { label: string; color?: LabelColor } }

它支持两种形式：

• 字符串形式：直接传入名称，如name: 'unit'；
• 对象形式：通过label指定名称、color指定颜色，如name: { label: 'unit', color: 'blue' }。

在源码中，LabelColor被定义为八个具体字面量，见 packages/vitest/src/types/general.ts#L53：

export type LabelColor = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white'

值得注意的是，该类型注释明确指出：这些颜色需要与 Tinyrainbow 的背景色（bg-colors）以及 CSS 的background-color保持兼容。这意味着同一个color值在终端中会映射为相应的 ANSI 背景色，而在 UI 界面中则对应同名的 CSS 颜色。

两种写法的配置示例

字符串写法

import { defineConfig } from 'vitest/config' export default defineConfig({ test: { name: 'unit', }, })

对象写法（带颜色）

import { defineConfig } from 'vitest/config' export default defineConfig({ test: { name: { label: 'unit', color: 'blue', }, }, })

两种写法等价地设置项目名称，区别仅在于对象写法额外控制了 CLI 与 UI 中展示名称所使用的颜色。

颜色系统：CLI 与 UI 的对应关系

color属性可选值固定为八种：black、red、green、yellow、blue、magenta、cyan、white。

需要理解两点限制：

1. 终端显示取决于配色方案：CLI 中实际呈现的颜色受终端自身的颜色主题影响，不同的终端模拟器/配色方案下观感可能不同；
2. UI 中与 CSS 等价：在 Vitest UI 中，这些颜色直接对应同名的 CSS 颜色值（blue即blue色，cyan即青色等）。

从实现层面看，CLI 报告器正是通过 tinyrainbow 的背景色 API 来渲染项目标签的。例如在 packages/vitest/src/node/reporters/base.ts#L1392-L1394 中，测试失败输出使用c.bgRed(c.bold(' FAIL '))渲染状态徽标，项目名称则经由formatProjectName处理，与颜色体系共用同一套颜色函数，这正是LabelColor需要与 Tinyrainbow 背景色对齐的源码原因。

多项目场景下的实战价值

name配置项最典型的应用场景是多项目工作区：当test.projects数组中定义了多个项目时，每个项目的名称会出现在终端输出中，方便开发者一眼定位测试归属：

import { defineConfig } from 'vitest/config' export default defineConfig({ test: { projects: [ { name: 'unit', include: ['./test/*.unit.test.js'], }, { name: 'e2e', include: ['./test/*.e2e.test.js'], }, ], }, })

配置完成后，CLI 中每条测试结果都会带上前缀（如unit、e2e），配合--project命令行过滤参数（源码见 packages/vitest/src/node/projects/resolveProjects.ts#L1082-L1084），即可按名称筛选要运行的项目。此外，项目名还会参与结果缓存键的生成（见 packages/vitest/src/node/cache/index.ts#L27-L33），因此名称也会影响缓存目录的隔离。

未配置 name 时的自动命名规则

当你不提供name时，Vitest 会按以下优先级自动分配名称（配置文档 中的 tip 说明）：

1. 读取package.json的name字段：如果项目由配置文件或目录指定，且该目录下存在package.json，则使用其中的name字段；
2. 回退到目录名：如果不存在package.json（或其中没有有效的name字段），则使用项目文件夹的 basename；
3. 内联项目使用数组索引：如果项目是直接定义在projects数组中的内联对象，Vitest 会分配一个等于该项目数组下标（0 起始）的数字名称，并在内部转为字符串。

这一规则在源码resolveProjectName函数中有完整实现，见 packages/vitest/src/node/projects/resolveProjects.ts#L1313-L1347。其核心逻辑为：

function resolveProjectName(name, workspacePath, containerLabel) { let { label, color } = typeof name === 'string' ? { label: name } : { label: '', ...name } if (!label) { if (typeof workspacePath === 'number') { label = workspacePath.toString() // 内联项目 → 数组索引 } else { const dir = workspacePath.endsWith('/') ? workspacePath.slice(0, -1) : dirname(workspacePath) const pkgJsonPath = resolve(dir, 'package.json') if (existsSync(pkgJsonPath)) { label = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')).name } if (typeof label !== 'string' || !label) { label = basename(dir) // 无 package.json → 文件夹名 } } } // 容器配置声明的项目会被容器名命名空间化 if (containerLabel) { label = `${containerLabel} (${label})` } return { label, color } }

从源码还可以看到一条文档未展开的细节：由容器配置（container config）声明的子项目，其名称会自动加上容器名前缀，例如app容器下的unit项目最终显示为app (unit)，这是为了避免多级工作区中出现歧义。

在 TestProject#name 文档中，给出了与上述规则对应的完整示例：'./packages/server'因存在package.json且 name 为@pkg/server而得名@pkg/server；'./utils'无package.json，取文件夹名utils；内联对象不自定义 name 时，按数组下标得名'2'；显式配置name: 'custom'的项目则得名custom。另外需要留意：如果根项目不在用户项目列表中，其name不会被解析。

重名约束：配置解析阶段即报错

Vitest 规定项目之间不能重名。若多个项目使用了相同的名称，Vitest 会在配置解析阶段直接抛出错误。源码中的校验逻辑位于 packages/vitest/src/node/projects/resolveProjects.ts#L145-L187，错误信息为：

Project name "xxx" is not unique. All projects should have unique names. Make sure your configuration is correct.

该校验通过维护seenNames集合实现：逐个登记项目名，一旦发现重复即抛出上述诊断。因此在实际配置多项目工作区时，应确保所有项目的名称（包括自动解析出的名称）互不冲突。

浏览器实例的命名继承规则

在浏览器测试模式下，可以为不同的浏览器实例分配不同名称（browser.instances 配置），示例：

import { defineConfig } from 'vitest/config' import { playwright } from '@vitest/browser-playwright' export default defineConfig({ test: { browser: { enabled: true, provider: playwright(), instances: [ { browser: 'chromium', name: 'Chrome' }, { browser: 'firefox', name: 'Firefox' }, ], }, }, })

浏览器实例的命名遵循两条约定（配置文档 中的 tip）：

1. 继承父项目名并追加浏览器名：浏览器实例会继承其父项目的名称，并以括号形式追加浏览器名称。例如项目名为browser、实例为 chromium 时，显示名称为browser (chromium)；
2. 无父项目名时默认用浏览器值：如果父项目未命名，或实例定义在根级（不在某个已命名项目内），实例名称默认取浏览器值本身（如chromium）。若想覆盖此行为，需在实例上显式设置name。

这一行为在源码的浏览器实例展开逻辑（packages/vitest/src/node/projects/resolveProjects.ts#L869-L978）中实现：展开实例时父项目名会从名称集合中移除，实例名称参与后续的唯一性校验；同时源码也约束了同一浏览器不能定义多个未命名的嵌套项目，重复时同样会抛出 "All projects should have unique names" 的错误，提示用户为多实例显式配置name。

通过 Node.js API 读取项目名

name配置的最终解析结果可通过 Node.js 高级 API 获取。使用createVitest创建进程后，遍历vitest.projects即可读取每个项目的name：

import { createVitest } from 'vitest/node' const vitest = await createVitest('test') vitest.projects.map(p => p.name) === [ '@pkg/server', 'utils', '2', 'custom' ]

这段示例清晰地展示了四种命名来源的最终效果：package.json的 name（@pkg/server）、文件夹 basename（utils）、内联项目数组索引（'2'）以及显式配置的 name（custom）。关于该 API 的更多细节，可参考 TestProject#name。

总结

name虽是一个看似简单的配置项，但它贯穿了 Vitest 的多个子系统：CLI/UI 的展示层（配合八种LabelColor颜色）、多项目工作区的区分与--project过滤、结果缓存隔离、以及浏览器实例的继承命名。理解其自动命名回退规则（package.jsonname → 文件夹名 → 数组索引）和重名校验约束，能够帮助你更合理地规划项目命名方案，让多项目、多浏览器实例的测试输出一目了然。

【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest