Vue3使用vue-i18n报createI18n is not a function错误

问题场景 #

在Vue3项目中引入i18n依赖，计划实现加泰罗尼亚语、西班牙语、英语三语国际化功能，项目运行时抛出createI18n is not a function类型错误，报错截图如下：

现有代码与配置 #

i18n.js配置代码 #

import { createI18n } from 'vue-i18n/dist/vue-i18n';

import ca from '../lang/ca.json';
import es from '../lang/es.json';
import en from '../lang/en.json';

const i18n = createI18n({
    locale: 'ca',
    messages: {
      ca, es, en
    }
});
export default i18n;

入口文件app.js代码 #

import { createApp } from "vue/dist/vue.esm-bundler.js";
import i18n from './i18n';

const app = createApp({});

app.use(i18n);
app.mount('#app');

package.json依赖配置 #

{
    "private": true,
    "scripts": {
        "watch": "vite",
        "dev": "vite build"
    },
    "devDependencies": {
        "@vitejs/plugin-vue": "^1.1.5",
        "@vue/compiler-sfc": "^3.0.6",
        "autoprefixer": "^10.4.7",
        "postcss": "^8.4.14",
        "sass": "^1.52.1",
        "tailwindcss": "^3.0.24",
        "vite": "^2.9.9",
        "vite-plugin-laravel": "^0.2.0-beta.12",
        "vue": "^3.2.36"
    },
    "dependencies": {
        "vue-i18n": "^8.27.1"
    }
}

错误根因 #

• 核心问题是依赖版本不匹配：当前安装的vue-i18n@8.27.1是适配Vue 2的版本，该版本不存在createI18n导出API，初始化逻辑为new VueI18n()，完全不兼容Vue3的插件注册机制。createI18n是适配Vue3的vue-i18n@9.x版本专属的初始化方法。
• 次要问题是导入路径写死：代码中从vue-i18n/dist/vue-i18n导入属于非标准路径，会绕过打包工具的模块解析规则，可能引发额外的模块导出识别错误。

修复步骤 #

1. 卸载不兼容版本，安装适配Vue3的vue-i18n版本，执行对应包管理命令：

# npm 环境
npm uninstall vue-i18n && npm install vue-i18n@^9

# yarn 环境
yarn remove vue-i18n && yarn add vue-i18n@^9

# pnpm 环境
pnpm remove vue-i18n && pnpm add vue-i18n@^9

2. 修改i18n.js配置，修正导入路径，补充适配Vue3组合式API的配置项，修改后代码如下：

// 直接从包根导入，交由打包工具解析对应模块
import { createI18n } from 'vue-i18n'
import ca from '../lang/ca.json'
import es from '../lang/es.json'
import en from '../lang/en.json'

const i18n = createI18n({
  legacy: false, // 关闭legacy模式，适配Vue3组合式API，支持useI18n调用
  locale: 'ca', // 默认展示语言
  fallbackLocale: 'en', // 文案缺失时的兜底语言
  messages: {
    ca,
    es,
    en
  }
})

export default i18n

3. 入口文件原有注册逻辑无需修改，重启开发服务或重新执行构建命令，错误即可消除。

内容的提问来源于stack exchange，提问作者Victor Matilla