本文详解如何在 Vue 3（Composition API）项目中为 Jest 单元测试正确配置 vue-i18n，解决 $t is not a function 等核心报错，涵盖插件注入、类型声明、模拟策略及常见陷阱。
本文详解如何在 vue 3（composition api）项目中为 jest 单元测试正确配置 vue-i18n，解决 `$t is not a function` 等核心报错，涵盖插件注入、类型声明、模拟策略及常见陷阱。
在 Vue 3 + TypeScript 项目中集成 vue-i18n 后，单元测试常因 $t 方法缺失而崩溃——典型错误如 TypeError: _ctx.$t is not a function。这并非代码逻辑问题，而是测试环境未正确提供 i18n 实例所致。与开发时自动挂载不同，Jest 测试需显式将 i18n 插件注入 mount 配置的 global.plugins 中，否则组件无法访问 $t、$i18n 等全局属性。
✅ 正确做法：在 mount() 中注入 i18n 实例
首先确保你已创建并导出 i18n 实例（推荐使用 Composition API 模式，即 legacy: false）：
// src/i18n/index.ts
import { createI18n } from 'vue-i18n';
import { de, en } from './locales';
export const i18n = createI18n({
legacy: false, // 关键！禁用 Vue 2 兼容模式
locale: 'de',
messages: { de, en }
});接着，在测试文件中导入该实例，并将其传入 mount 的 global.plugins：
// DudDialog.spec.js
import { mount } from '@vue/test-utils';
import { createPinia } from 'pinia';
import { i18n } from '@/i18n'; // ✅ 导入真实 i18n 实例
import DudDialog from '@/components/DudsView/DudDialog.vue';
describe('DudDialog.vue', () => {
const pinia = createPinia();
it('displays the form fields correctly', () => {
const wrapper = mount(DudDialog, {
global: {
plugins: [pinia, i18n], // ✅ 关键：将 i18n 加入 plugins 数组
stubs: ['v-app', 'v-dialog', /* ... */],
},
props: { dud: new Dud('Test') }
});
// 此时 $t 可正常使用，模板渲染无报错
expect(wrapper.find('[label="Typ"]').exists()).toBe(true);
});
});⚠️ 注意：
plugins是数组，必须包含i18n（而非字符串'vue-i18n'），且顺序无关；但务必确保i18n实例已初始化（不为undefined）。立即学习“前端免费学习笔记（深入）”；
? 补充：TypeScript 类型支持（防 TS2339 报错）
若在 .spec.ts 中使用 wrapper.vm.$t(...) 仍遇 TS 错误，需补充类型声明：
// src/types/shims-vue-i18n.d.ts
import 'vue-i18n';
import type { ComponentCustomProperties } from 'vue';
import type { I18n } from 'vue-i18n';
declare module 'vue' {
interface ComponentCustomProperties {
$t: I18n['t'];
}
}并在 tsconfig.json 的 include 中加入该文件路径：
{
"include": ["src/**/*", "src/types/shims-vue-i18n.d.ts"]
}? 替代方案：轻量 Mock（适用于无真实翻译需求场景）
若仅需通过测试、无需真实翻译逻辑，可快速 mock $t：
const wrapper = mount(DudDialog, {
global: {
mocks: {
$t: (key: string) => `{{${key}}}` // 返回占位符，避免报错
},
stubs: [...],
},
props: { dud: new Dud('Test') }
});但注意：mocks 在 Vue Test Utils v2+ 中已被标记为 deprecated，官方推荐优先使用 plugins 注入真实实例，以保障测试真实性与可维护性。
? 总结关键点
- ❌ 错误：仅 stub 组件、忽略 i18n 插件注入 →
$t is not a function - ✅ 正确：
global.plugins: [pinia, i18n]→ 提供完整 i18n 上下文 - ✅ 必配：
legacy: false+shims-vue-i18n.d.ts→ 解决 TS 类型报错 - ⚠️ 警惕：
i18n实例导出路径错误、未初始化、或版本不匹配（Vue 3 请用vue-i18n@^9.x）
遵循以上实践，即可彻底告别 Jest 中 i18n 的“失联”问题，让国际化组件测试稳定、可靠、可扩展。
