一条 i18n 文案让全站显示 key:vue-i18n 的 @ 陷阱

2026-11-19 前端开发 有希 38 次瀏覽

页面没有报 404,也不是缺某个 key,但所有 t() 都变成了 pages.xxx.title 这样的裸键名。控制台还没有常见的 Not found 'xxx' key。这类问题的根因通常只有一条:某个语言包里有一段文案无法编译,整份语言包加载失败。本文用门户里真实的 @ 文案事故,说明 vue-i18n 的消息语法、错误码 10,以及怎么让检查脚本提前拦住。

现象:不是缺 key,是整个语言包没装上

缺 key 和编译失败看起来都像“文案没出来”,但表现不同:

现象缺 key消息编译失败
页面文案只有缺少的那条显示 key整站所有 t() 都显示 key
控制台反复提示 Not found 'xxx' key通常没有 Not found
开发覆盖层一般没有Invalid linked format (error code: 10)
影响范围单条整份 locale

门户的 i18n 文案放在 i18n/locales/zh.ts、en.ts、zh-Hant.ts。只要其中一份在加载时编译失败,Vue I18n 就不会把它注册成完整的 messages 对象,页面上的 t() 自然全部回退成键名。

最小复现:文案里出现一个裸 @

在 zh.ts 里写一段 curl 说明:

export default {
  pages: {
    toolCurlBuilder: {
      noteBody: '-d 会把 @ 开头的值当成文件名'
    }
  }
}

访问 /toolkit/curl-builder,开发环境会出现类似错误:

[plugin:unplugin-vue-i18n:resource] Invalid linked format (error code: 10)

注意这个 @ 不在行首,而是在句子中间。很多人以为只有 @:key 这种写法才会触发 linked message,实际上裸 @ 后面跟着内容,也会被解析成链接消息的开头,随后因为格式不完整而编译失败。

把文案改成“at 符号”即可:

noteBody: '-d 会把 at 符号开头的值当成文件名'

这也是门户现在的写法。提交 a476dc8 里记录了这次修改,错误字符串本身没有进入版本库,所以后来只能从提交说明和检查脚本反推触发条件。

根因一:@、{}、| 都是消息语法

vue-i18n 的消息不是普通字符串,而是一套带语法的模板:

字符含义容易踩的写法
@linked message,例如 @:common.save句子里写 @ 开头、回复 @{name}
{}插值,例如 {count}示例 JSON、curl 的 {} 直接写进文案
``复数分隔
$普通字符一般安全,但不要和 linked message 混用

真正危险的不是这些字符本身,而是“把代码示例当文案”。curl 参数、JSON、模板字符串里经常出现 @、{}、|,直接塞进 locale 就会参与编译。门户的做法是把这类示例放进组件常量或代码块,不放进 i18n 消息。

如果确实要在文案里显示 @,可以用字面量插值:

noteBody: "参数以 {'@'} 开头时会被当成文件名"

但更推荐直接写“at 符号”。少一层语法,就少一个编译失败的机会。

根因二:默认编译只产 AST,不会主动抛错

vue-i18n 的消息编译器在默认模式下只负责把字符串解析成 AST,遇到语法错误不一定立刻抛异常。真正加载语言包时,JIT 编译才会触发错误。门户的 check:i18n 脚本就是按这个路径做的:

import { baseCompile } from '@intlify/message-compiler'

baseCompile(message, {
  mode: 'normal',
  jit: true,
  onError(error) {
    throw error
  }
})

脚本先用 esbuild 把三份 locale 打包,展平成 key -> message,再逐条编译。错误码 10 对应 INVALID_LINKED_FORMAT,输出格式大致是:

[zh] pages.toolCurlBuilder.noteBody
  文案: -d 会把 @ 开头的值当成文件名
  错误: Invalid linked format (code 10)
有 1 条无法编译(共 4672 条)

最后退出码为 1。这个检查必须在 CI 或提交前跑,因为浏览器里只会在访问到对应语言时才暴露问题,而且一旦暴露就是整站。

修复:把示例移出 locale,把检查放进 CI

修复分两层:

  1. 文案层:去掉裸 @、裸 {}、裸 |,或者用字面量插值转义。
  2. 工程层:把 pnpm check:i18n 加进提交前检查,别等页面变裸键名才发现。
pnpm check:i18n

通过时输出:

全部通过,共 4672 条文案

失败时按 key、文案、错误码三段打印,并返回非零退出码。这个脚本只检查静态文案,不检查运行时动态拼接的 key;动态 key 仍然要靠类型约束或页面冒烟。

如果团队里经常有人把 curl 示例写进文案,可以在评审时加一条规则:locale 文件只放用户可见的自然语言,代码示例放组件常量或 Markdown。这条规则比记住一堆转义写法更可靠。

验证:先制造一条错误,再确认检查能拦住

检查项操作期望结果
正常文案pnpm check:i18n全部通过,共 4672 条文案
裸 @临时在某个文案里加 @ 开头输出 Invalid linked format (code 10),退出码 1
修复后改成“at 符号”再次全部通过
页面访问 /toolkit/curl-builder文案正常,不再显示 key

负向验证很重要:如果只跑一次“全部通过”,无法确认脚本真的能抓到错误。故意加一条坏文案,确认它报错,再还原,才算验证过检查链路。

边界与坑

缺 key 和编译失败要分开排查。 缺 key 会有 Not found,编译失败通常没有。先看开发覆盖层有没有 error code: 10,再看对应 locale 文件。

不是所有 @ 都要删。 @:common.save 是合法的 linked message;{'@'} 是合法的字面量插值。危险的是“想显示 @,却写成了裸 @”。

{} 只在需要插值时使用。 示例 JSON 里的 {} 不是插值,放进 locale 会被当成占位符。两个连续花括号在 Vue 模板里还有特殊含义,博客正文也不要直接写。

检查脚本不覆盖动态 key。 t('pages.' + name) 这种拼接无法静态展开,类型检查也未必能发现。动态 key 要有白名单或运行时兜底。

语言包是整份加载的。 不要以为“只有一条文案坏了,其他还能用”。JIT 编译失败时,整份 messages 都不会注册,表现就是全站裸键名。

相关工具

curl 参数里的 @ 是这次事故的来源,可以用 curl 命令生成工具 看参数实际怎么拼接;需要把请求转成代码时,用 curl 转代码工具 对照生成的字符串。更多 i18n 和前端排错记录放在 技术笔记。

FAQ

为什么整站都变成 key,而不是只有一条?

因为语言包是整份编译、整份注册的。一条消息编译失败,整份 locale 加载失败,所有 t() 都找不到对应文案,于是回退成键名。

错误码 10 是什么?

INVALID_LINKED_FORMAT,表示 linked message 格式不完整。最常见的原因是文案里出现了裸 @,后面没有合法的 :key 或 {name}。

文案里确实要显示 @ 怎么办?

写成 {'@'} 做字面量插值,或者直接写“at 符号”。不要写裸 @,也不要把 curl/JSON 示例整段放进 locale。

check:i18n 通过就一定没问题吗?

它覆盖静态文案,不覆盖动态拼接的 key 和运行时才加载的远程文案。静态检查通过后,仍然要对关键页面做一次语言切换冒烟。

i18n 文案的问题最好在提交前解决:locale 里只放自然语言,代码示例放组件,check:i18n 进 CI。这样就不会出现“改了一条说明,整站变 key”的情况。

評論

登入後即可參與評論

還沒有評論,來說兩句吧

相關文章