企业官网建设流程全解析

很多人写 Vue 组件测试，都是从自己封装的业务组件入手，一套组合拳打完，感觉挺顺手。结果到了项目里引入 Naive UI 这种第三方组件库，第一次给页面里的NModal、NSelect、NDataTable写测试，就发现情况完全不对，按钮点了没反应，弹窗找不到 DOM，虚拟表格数据一行都渲染不出来，连wrapper.find都拿不到节点。这不是你写测试的姿势有问题，而是 Naive UI 这套组件库的设计范式，和普通的业务组件有本质区别，需要用一套专门针对它的方法论来做测试。这篇文章就是我最近在一个中型后台项目里，从零开始给 Naive UI 组件写 Jest 测试的完整复盘，从工程配置到核心 API 用法，再到一个个真实组件的测试实例，全流程拆开讲给你听。

标题里的“从0到1”不是夸张。我接手那个项目的时候，测试覆盖率还是零，装完 Jest 跑第一遍，光是环境就折腾了小半天。这套东西如果没有人告诉你哪些坑在哪儿，自己摸索的成本确实不低。这篇文章适合谁？如果你正准备给 Vue 3 + Vite + TypeScript 的项目补测试，项目里大量使用了 Naive UI 组件库，又想搞清楚@vue/test-utils到底怎么和 Naive UI 配合，那你来对了。我会从搭建一个最小可用测试环境开始，逐步讲到什么时候用mount什么时候用shallowMount、Teleport 组件怎么测、虚拟列表怎么 Mock、为什么 Naive UI 的样式在测试环境里会“消失”以及怎么处理，最后附上我踩过的坑和排查手册。

1. 认识 Naive UI：为什么组件测试要单独一套方法论

先把 Naive UI 的特点梳理清楚，因为它的所有测试特性，本质上都是它的这几个设计特性衍生出来的。你如果不理解这一点，后面遇到任何诡异的问题，都只能靠网上搜答案碰运气。

1.1 对 Vue 3 的深度依赖

Naive UI 是纯 Vue 3 组件库，完全不兼容 Vue 2。它用上了 Composition API 的大量特性，比如provide/inject、Teleport、响应式系统的高级用法。这意味着在写测试的时候，你必须确保测试环境是完整的 Vue 3 运行时，并且所有组件都使用的是同一个 Vue 实例。如果测试环境里混入了 Vue 2 的依赖，或者把组件库外部的全局配置搞错了，最常见的结果就是ProvidePlugin之类的警告，或者组件直接不渲染。

我遇到过最典型的情况是，项目里某个依赖间接引入了 Vue 2，结果 Vue Test Utils 挂载NButton的时候直接createApp失败。这种错误不在代码层面，而在依赖和包管理层面，排查起来非常恶心。

1.2 代码即 API：一个组件一棵树

Naive UI 的组件设计，大量使用复合组件模式。比如NDataTable内部集成了列配置、分页、排序、过滤、展开行；NSelect集成了选项搜索、远程加载、多选标签；NForm集成了表单项校验规则。这些集成在业务上是极大的便利，但在测试上是极大的挑战——因为你要测试的不仅仅是一个组件的表面行为，而是这颗组件树内多个子组件之间的交互。

举个例子，NForm的校验逻辑触发表单错误提示，实际上依赖内部NFormItem的状态管理。如果你用shallowMount把NFormItem给 stub 了，校验错误提示就永远无法触发，整个测试就失去意义。这是很多人写 Naive UI 测试时被卡住的最主要原因，后面我会专门讲怎么处理组件树的问题。

1.3 CSS-in-JS：样式是运行时生成的

Naive UI 的样式方案不是传统的全局 CSS 文件，而是在运行时通过css-render生成样式标签，再动态地插入到<head>里。测试环境下，jsdom虽然能模拟 DOM，但对于样式计算的支持非常弱。你测试的时候，getComputedStyle拿到的值基本上是空的，布局信息更不用想。

这不是 bug，而是 Naive UI 工作方式的正常表现。测试里如果能断言到样式值，是意外惊喜；断不到，几乎可以肯定是环境限制，不是测试目标本身的问题。这条认知很重要，它能帮你省掉许多无谓的排查时间。

2. 环境搭建与工程配置：Vite + TypeScript + Jest 组合拳

Jest 在 Vue 2 时代是绝对的霸主，但到了 Vue 3 + Vite 时代，处境微妙。Vite 原生用 ESM，而 Jest 默认用 CommonJS，两者在模块转换上需要大量胶水代码。我先来整理一套稳定的配置方案，再讲清楚每一行配置背后的意义，不然你抄了配置出了错还是不知道怎么改。

2.1 Jest 还是 Vitest？

先说结论：如果你是从零开始，我强烈建议你优先考虑 Vitest。Vitest 原生支持 Vite 配置，对 ESM 和 TypeScript 的开箱即用体验完美，速度还比 Jest 快。但题目的场景是 Jest，而且很多公司现有的持续集成环境、覆盖率平台、代码质量工具还停留在 Jest 生态。所以这篇文章还是以 Jest 为主线，但在合适的地方我会提醒哪些地方 Vitest 可以用更简单的方案替代。

2.2 安装依赖与 package.json 配置

先装一套最小集合：

npm install jest @vue/test-utils @vue/vue3-jest @types/jest -D

如果你的项目用的 TypeScript，还需要装ts-jest或者直接用@vue/vue3-jest配合babel-jest。我最稳妥的方案是@vue/vue3-jest处理.vue文件，ts-jest处理.ts文件，两条链路互不干扰。

然后是jest.config.js的关键配置：

module.exports = { testEnvironment: 'jsdom', transform: { '^.+\\.vue$': '@vue/vue3-jest', '^.+\\.tsx?$': 'ts-jest', }, moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1', '^vue$': 'vue/dist/vue.esm-bundler.js', }, setupFilesAfterEach: ['<rootDir>/tests/setup.ts'], testMatch: ['**/__tests__/**/*.spec.(ts|tsx)'], };

这里有一个我在实际项目中踩过的深坑。如果不把'^vue$'映射到vue/dist/vue.esm-bundler.js，Vue 在 Jest 环境里默认走的是运行时版本，而 Naive UI 很多组件用到了模板编译的特性，会出现组件渲染空白的问题。加了这行映射，用的是完整版 Vue，带编译器，才能正常渲染 Naive UI 的模板。

2.3 TypeScript 的 Jest 配置细节

用ts-jest的时候，TypeScript 的版本和 Jest 的版本要匹配。我的项目里 TypeScript 是 5.x，ts-jest需要装最新的 29.x 系列。如果版本不对，最经典的报错是Unknown identifier或者模块表找不到，看着像代码问题，实际上就是版本系列对不上。

tsconfig.json里需要有一个环境集合补丁，让 TypeScript 认识 Jest 的全局变量和 DOM 类型：

{ "compilerOptions": { "types": ["jest", "node", "@types/jest"] } }

2.4 全局配置与 setup 文件

setupFilesAfterEach里写的脚本会在每个测试文件运行之前执行，适合放全局 Mock 和清理逻辑。我的setup.ts长这样：

import { config } from '@vue/test-utils'; import { vi } from 'vitest'; // 如果你还在 Jest 里，实际是 jest // 确保每个测试之后清理 DOM afterEach(() => { document.getElementsByTagName('body')[0].innerHTML = ''; vi.restoreAllMocks(); });

document.body.innerHTML = ''这个清理非常重要。因为 Naive UI 的弹层组件（NModal、NSelect的下拉面板、NMessage、NNotification）默认 Teleport 到 body 下，如果上一个测试的弹层残留，下一个测试找节点的时候极容易误判。

3. 核心 API 使用策略：mount 与 shallowMount 的抉择

Vue Test Utils 的mount和shallowMount的选择，在 Naive UI 测试里直接决定了你测试的成败。我见过不少人拿 Java 后端那套“单元测试必须 Mock 掉所有依赖”的思路，一上来就shallowMount，结果 Naive UI 组件几乎啥都测不了。这不能怪他们，是这套思维定式不适合这个场景。

3.1 shallowMount 的“本地依赖”误区

shallowMount会把所有子组件替换成存根（stub），也就是说不渲染子组件的真实内容。对于业务组件来说，这是合理的，因为你想测的是这个组件自身的逻辑。但 Naive UI 的复合组件，比如NForm，它的核心功能就是靠内部的NFormItem、NInput等子组件协同完成的。如果子组件被 stub，你触发校验、读取错误消息等操作都会失效。

3.2 Naive UI 组件测试的正确姿势：mount

我的实际经验是：Naive UI 组件测试，默认用mount挂载完整组件树。哪怕NButton这种简单组件，也用mount，因为它的点击事件至少涉及NButton自身的事件监听和v-if的图标渲染逻辑。

来看一个最简单的NButton测试：

import { mount } from '@vue/test-utils'; import { NButton } from 'naive-ui'; const wrapper = mount(NButton, { props: { type: 'primary', }, slots: { default: 'Click me', }, }); test('NButton 渲染默认插槽', () => { expect(wrapper.text()).toContain('Click me'); });

3.3 为什么浅渲染在 Naive UI 测试里不是不能用

当然，我并不是说shallowMount完全不能用。如果你的目标是测试一个业务组件，而这个业务组件只使用了NButton作为展示组件，不涉及它的交互逻辑，那shallowMount完全可以，因为你不关心 NButton 内部怎么实现。这种场景下 shallowMount 的 stub 可以避免 Naive UI 内部过多 DOM 结构干扰你对业务组件的断言。

但有一点必须提醒：shallowMount的 stub 是全局替换所有子组件，如果你想保留某个 Naive UI 组件的真实行为，就得用stubs配置手动指定：

stubs: { 'n-button': false // 或者使用真实的组件定义 }

这种选择性 stub 的思路，是浅渲染在 Naive UI 测试里唯一正确的用法，我建议你直接用我下面这套逻辑来决策：

4. Naive UI 进阶组件测试：弹窗、表单、表格与虚拟列表实战

进了正题，这一章我按从易到难的顺序，把 Naive UI 里最常用、也最容易踩坑的几个组件测试逐一拆开。每个实例都是我在实际项目中跑通的，包含完整的代码和操作细节。

4.1 NButton 与事件触发：异步优先原则

NButton虽然是基础组件，但 Naive UI 内部对点击事件做了很多封装，尤其是在设置了loading属性的时候，按钮会禁用并显示 loading 状态。测试的时候，直接.trigger('click')可能不会生效，因为 Naive UI 的按钮事件经过了内部节流或者状态锁定的处理。

我的建议是，对NButton的点击测试，做两步走：

test('NButton 点击触发事件', async () => { const handleClick = jest.fn(); const wrapper = mount(NButton, { props: { onClick: handleClick }, }); await wrapper.trigger('click'); expect(handleClick).toHaveBeenCalled(); });

关键是await。Vue 的事件处理内部有异步更新队列，不await的话，断言大概率比 DOM 更新跑得早。

4.2 NModal 弹层组件：Teleport 和 attachTo 的深水区

NModal是 Naive UI 测试里最容易让人崩溃的组件。默认情况下，NModal渲染到 document.body 下（通过 Teleport）。这意味着wrapper（挂载在 div 上的）根本找不到弹窗内容。

基础入门写法：

import { NModal, NButton } from 'naive-ui'; import { mount } from '@vue/test-utils'; test('NModal 显示与隐藏', async () => { const wrapper = mount(NModal, { props: { show: true, 'onUpdate:show': (val: boolean) => { // 在真实业务里，这里是 v-model 的更新逻辑 }, }, slots: { default: '弹窗内容', }, }); await wrapper.vm.$nextTick(); // 弹窗内容渲染在 body 下面，不能用 wrapper 查找 expect(document.body.textContent).toContain('弹窗内容'); });

这是最直接的写法。但它有两个问题：

1. document.body里可能包含之前测试残留的元素。
2. 在测试里，show是 props，你没法通过组件内部状态去控制它。真实业务里，弹窗的显隐由父组件的ref和v-model控制。

所以我的建议是：测试弹窗组件，不要直接测NModal本身，而是测它外面的业务组件。比如：

<template> <div> <NButton @click="showModal = true">打开弹窗</NButton> <NModal v-model:show="showModal"> <div class="modal-content">确认删除吗？</div> </NModal> </div> </template>

测试这个业务组件的时候，用mount整体挂载，然后点击按钮触发弹窗打开，再断言document.body里是否出现了.modal-content。这里有一个细节：把页面整体挂载后，NModal的 Teleport 内容会挂到 body，但wrapper本身还挂在原 div 上，所以查询.modal-content一定要用document.body.querySelector('.modal-content')或者document.body.textContent，不要用wrapper.find。

4.3 NForm 表单校验：与子组件的联动

表单校验是 Naive UI 高价值功能，测试它的最大障碍是：触发校验需要真实填写或改变NInput的值，而NInput的值改变又依赖v-model传递事件。这形成了一条链路：你的测试代码要模拟用户输入事件，而这个事件必须被NFormItem捕获并触发校验规则。

直接给代码：

import { mount } from '@vue/test-utils'; import { NForm, NFormItem, NInput, NButton } from 'naive-ui'; const TestForm = { components: { NForm, NFormItem, NInput, NButton }, template: ` <NForm :model="formData" :rules="rules" ref="formRef"> <NFormItem path="name" label="姓名"> <NInput v-model:value="formData.name" placeholder="请输入姓名" /> </NFormItem> <NButton attr-type="submit">提交</NButton> </NForm> `, data() { return { formData: { name: '' }, rules: { name: { required: true, message: '请输入姓名', trigger: ['blur', 'input'] }, }, }; }, }; test('NForm 必填校验', async () => { const wrapper = mount(TestForm); const input = wrapper.find('input'); // 触发 blur 事件，因为 trigger 里有 blur await input.trigger('blur'); await wrapper.vm.$nextTick(); expect(document.body.textContent).toContain('请输入姓名'); });

这里容易犯的错误是，NForm的校验提示默认也是通过某种 Teleport 方式渲染到页面上的（具体的要看版本，有些版本是直接插入，有些也挂到 body）。万一你wrapper里找不到错误提示，尝试去document.body里找。这是我个人反复踩过的地方。

4.4 NSelect 下拉：数据加载与选项渲染

NSelect背后涉及远程搜索、下拉面板的 Teleport 渲染、选项的点击选择，链路也不短。测试时核心目标是：渲染选项、点击选项触发 value 变化。

import { mount } from '@vue/test-utils'; import { NSelect } from 'naive-ui'; test('NSelect 选项渲染与选择', async () => { const handleUpdate = jest.fn(); const wrapper = mount(NSelect, { props: { options: [ { label: 'Apple', value: 'apple' }, { label: 'Banana', value: 'banana' }, ], 'onUpdate:value': handleUpdate, }, }); // 打开下拉 await wrapper.find('.n-base-selection').trigger('click'); await wrapper.vm.$nextTick(); // 下拉面板的选项渲染在 body const option = document.body.querySelector('.n-select-option'); expect(option.textContent).toContain('Apple'); await option.click(); expect(handleUpdate).toHaveBeenCalledWith('apple'); });

关键点：下拉选项渲染在 body 里，一定要从 body 里查询并 click。而且NSelect这类组件的内部 DOM 结构在不同版本里有差异，建议用比较稳定的 class（例如.n-base-selection）作为触发器，不要用过脆的快照选择器。

4.5 NDataTable：虚拟列表与 getBoundingClientRect 的坑

NDataTable是 Naive UI 中测试复杂度最高、也最能体现框架设计差异的组件。它默认开启虚拟滚动，意味着只有视口内的行才会真实渲染到 DOM。在jsdom里，所有元素都被视为 0 宽 0 高，所以虚拟列表不会渲染任何行——这就是很多人在测试 NDataTable 时“一行数据都看不到”的根本原因。

解决方案是 MockgetBoundingClientRect和ResizeObserver：

beforeAll(() => { Object.defineProperty(HTMLElement.prototype, 'clientHeight', { configurable: true, value: 500, }); Object.defineProperty(HTMLElement.prototype, 'getBoundingClientRect', { configurable: true, value: () => ({ height: 40, width: 200, top: 0, left: 0, bottom: 40, right: 200 }), }); // Mock ResizeObserver global.ResizeObserver = class { observe() {} unobserve() {} disconnect() {} }; });

然后测试表格渲染：

test('NDataTable 渲染数据行', async () => { const columns = [ { title: '姓名', key: 'name' }, { title: '年龄', key: 'age' }, ]; const data = [ { name: '张三', age: 30 }, { name: '李四', age: 25 }, ]; const wrapper = mount(NDataTable, { props: { columns, data }, }); await wrapper.vm.$nextTick(); // 虚拟滚动 Mock 后，断言表格主体区域能渲染出至少两行数据 const rows = wrapper.findAll('tr'); expect(rows.length).toBeGreaterThan(1); });

如果你的测试环境没有加 ClientHeight 的 Mock，NDataTable 可能直接渲染一个高度为 0 的容器，一行都不给你渲染。这个坑特别隐蔽，报错还没有提示，只有断言失败后你才会怀疑行数为什么是 0。

4.6 NMessage 与 NNotification：编程式组件的测试

Naive UI 的NMessage和NNotification是编程式 API，意味着你需要通过useMessage()拿到实例，再调用实例的方法触发显示，最后断言页面中出现对应的文本。测试这种组件时，最关键的步骤是确保NMessageProvider包裹了你的组件：

import { NMessageProvider, useMessage } from 'naive-ui'; import { defineComponent, h } from 'vue'; import { mount } from '@vue/test-utils'; const TestComponent = defineComponent({ setup() { const message = useMessage(); return () => h('button', { onClick: () => message.success('保存成功') }, '保存'); }, }); test('NMessage 成功提示', async () => { const wrapper = mount({ components: { TestComponent }, template: `<n-message-provider><test-component /></n-message-provider>`, }); await wrapper.find('button').trigger('click'); await wrapper.vm.$nextTick(); expect(document.body.textContent).toContain('保存成功'); });

NMessage 渲染出来的消息默认挂到 body 下，所以查询还是那句老话，去 body 里找。

5. 异步、Mock 与快照：让测试稳定不飘

组件测试写着写着就会遇到执行顺序、真实请求、样式类对齐之类的问题，这一章我把异步时序、Mock 策略和快照测试的经验一次性讲清楚。

5.1 setTimeout、requestAnimationFrame 与异步组件

Naive UI 的很多交互内置了动画效果，比如 NModal 的展开收起、NSelect 的下拉动画。这些动画底层用了setTimeout、requestAnimationFrame。用 fake timers 控制十分必要。

jest.useFakeTimers(); test('NModal 动画完成后内容可见', async () => { const wrapper = mount(...); await wrapper.vm.$nextTick(); // 等待初始化渲染 jest.runAllTimers(); // 触发动画回调 await wrapper.vm.$nextTick(); expect(document.body.textContent).toContain('内容'); });

这里有一个容易忽略的点：如果你在测试里用了 jest fake timers，再配合await wrapper.trigger('click')，Vue 内部的nextTick是基于微任务的，不会被 fake timers 影响，但 Naive UI 的内部动画回调是基于宏任务的，必须手动runAllTimers()或者advanceTimersByTime()。两者配合使用，这个测试才稳定。

5.2 Mock 网络请求与接口数据

页面组件测试不可避免会碰到 axios 请求。强烈建议使用jest.mock把请求模块 mock 掉，而不是在测试里等待真实接口。我之前遇到过一个项目，组件加载时根据接口返回值决定下一步操作，接口偶尔返回慢导致测试时好时坏。最后用jest.mock固定返回值，测试才稳定下来。

jest.mock('@/api/user', () => ({ fetchUserInfo: jest.fn().mockResolvedValue({ id: 1, name: '测试用户' }), }));

5.3 快照测试的取舍

对 Naive UI 组件做快照测试，我个人持保留态度。因为 Naive UI 的 DOM 结构详细、内部类名复杂、不同版本之间的 DOM 结构可能完全不同，一个快照测试在组件库升级后大概率会失败。快照测试适合对业务组件自身的渲染结构做保护，不适合对 Naive UI 这种底层库的渲染做快照。真要保护，建议只对核心业务节点做定向断言，不要整树快照。

6. 常见问题与排查技巧实录

下表是我这段时间实战中遇到的高频问题，整理成速查手册。每一条都是真实场景里跑过、修过、写下来的。

再看两个容易现场踩坑的具体问题。

遇到“组件挂载了但渲染不出来”的时候，先不要慌着改动业务代码，建议按顺序排查：第一步，确认 Vue 版本是否映射到了 esm-bundler 版本；第二步，确认组件树是否被shallowMount误伤；第三步，确认是否使用了 Teleport 并且查询位置错了；第四步，确认是否有异步操作没有await。百分之八十的问题出在这四步。

另一个我反复遇到的坑是异步测试的done回调。如果你在测试里直接用了jest.useFakeTimers()，而回调里又有done，两者会打架。正确的做法是先把 fake timers 关了，或者用jest.useRealTimers()临时切回真计时器，然后调用done。这个细节不处理好，测试会一直超时报错，而且报错信息一点都不友好，排查起来特别费劲。

7. 在真实项目中的测试策略小结

以一个中型后台项目为例，页面大概 30 个，组件 80 个。我的测试策略可以总结成一条主线：优先覆盖页面级用户主流程，覆盖 Naive UI 复合组件的关键交互，而不是追求对每个组件都做单元测试。深层原因是，组件测试的目的是保护业务逻辑不因修改而挂掉，而不是证明 Naive UI 自己工作正常。后者是 Naive UI 开源团队的事，我们这些使用者要守住的，是自己的业务断言和 UI 交互链路。

我个人在实际操作中的体会是：在 Naive UI 生态里写测试，你越是对“单元测试必须隔离一切依赖”的理念奉若神明，就越容易寸步难行。它是高内聚复合组件库，正确的测试策略是站在用户视角，驱动完整的组件树去模拟真实的交互流程。这套心得后续还可以扩展到其他 Vue 3 组件库的测试上，比如 Ant Design Vue 和 Element Plus，很多思路是相通的。只是 Naive UI 的 Teleport 和虚拟列表更激进，而它的 CSS-in-JS 会让一些传统的快照测试显得无足轻重。抓住这两个核心差异，你就能在 Jest 和 Vue Test Utils 的环境里游刃有余。