@liujitcn/kratos-uni-app-cli 0.0.37 → 0.0.39

package/README.md

@@ -48,3 +48,14 @@ pnpm dlx @liujitcn/kratos-uni-app-cli create my-app --with @acme/pay
 `pnpm` 与 `tar`，不安装生成项目的依赖，并在结束后清理临时目录。
 
 包构建和脚手架验证命令见 [workspace 文档](../../README.md)。
+
+
+### CLI 生成边界
+
+CLI 直接生成完整宿主、本地业务模块、四种语言源文件与注册入口、类型检查、lint 和打包配置。
+支持本地 `system` 与其他模块一起创建；管理端本地 System 继承内置能力，运行时只注册一次，
+构建仍扫描内置源码。应用端本地模块使用独立导入别名，保留内置 System。
+
+通过 `--kratos-project` 生成与 Go 后端配套的前端：H5 输出到 `backend/data/<terminal>`，
+管理端 CLI 同时在 workspace 父目录创建共享 `Makefile` 与 `scripts`。Go 调用方仅传参执行 CLI。
+新增语言或修改语言文件后运行 `pnpm i18n:sync`；`pnpm i18n:check` 校验注册文件是否同步。

package/bin/kratos-uni-app.mjs

@@ -8,10 +8,12 @@ if (args[0] !== 'create' || !args[1]) {
 } else {
   const modules = []
   const packages = []
+  let kratosProject = false
   for (let index = 2; index < args.length; index += 1) {
     if (args[index] === '--module' && args[index + 1]) modules.push(args[++index])
     else if (args[index] === '--with' && args[index + 1]) packages.push(args[++index])
+    else if (args[index] === '--kratos-project') kratosProject = true
     else throw new Error(`未知参数：${args[index]}`)
   }
-  scaffoldKratosApp(args[1], { modules, packages })
+  scaffoldKratosApp(args[1], { modules, packages, kratosProject })
 }

package/package.json

@@ -7,13 +7,14 @@
     "type": "git",
     "url": "git@github.com:liujitcn/kratos-admin.git"
   },
-  "version": "0.0.37",
+  "version": "0.0.39",
   "type": "module",
   "files": [
     "assets",
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "bin": {
     "kratos-uni-app": "./bin/kratos-uni-app.mjs"

package/src/index.mjs

@@ -1,4 +1,12 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs'
 import { basename, resolve } from 'node:path'
 
 const cliPackage = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
@@ -22,43 +30,9 @@ export function scaffoldKratosApp(targetPath, options = {}) {
   )
 
   write(target, 'pnpm-workspace.yaml', 'packages:\n  - apps/*\n  - packages/modules/*\n')
-  write(
-    target,
-    'package.json',
-    json({
-      name: projectName,
-      description: `Independent pnpm workspace for ${projectName}.`,
-      private: true,
-      packageManager: 'pnpm@10.13.1',
-      scripts: {
-        prepare: 'pnpm run prepare:modules',
-        'prepare:modules': 'node -e "process.exit(0)"',
-        'dev:h5': 'pnpm --filter @liujitcn/kratos-uni-app dev:h5',
-        'dev:mp-weixin': 'pnpm --filter @liujitcn/kratos-uni-app dev:mp-weixin',
-        'build:h5': 'pnpm --filter @liujitcn/kratos-uni-app build:h5',
-        'build:mp-weixin': 'pnpm --filter @liujitcn/kratos-uni-app build:mp-weixin',
-        tsc: 'pnpm --recursive --if-present run tsc',
-      },
-      devDependencies: {
-        '@dcloudio/types': '^3.4.8',
-        '@rushstack/eslint-patch': '^1.1.4',
-        '@uni-helper/uni-app-types': '1.0.0-alpha.6',
-        '@uni-helper/uni-ui-types': '1.0.0-alpha.6',
-        '@vue/compiler-sfc': '3.4.21',
-        '@vue/eslint-config-prettier': '10.2.0',
-        '@vue/eslint-config-typescript': '14.7.0',
-        '@vue/tsconfig': '^0.7.0',
-        eslint: '9.39.1',
-        'miniprogram-api-typings': '^4.0.5',
-        prettier: '3.6.2',
-        typescript: '5.4.5',
-        'vue-tsc': '^1.8.8',
-      },
-      pnpm: {
-        onlyBuiltDependencies: ['esbuild', 'core-js', 'core-js-pure', 'vue-demi'],
-      },
-    }),
-  )
+  renderWorkspaceTemplates(new URL('../templates/workspace/', import.meta.url), target, {
+    __PROJECT_NAME__: projectName,
+  })
   writeEnvironmentFiles(target)
   copyFileSync(
     new URL('../assets/favicon.ico', import.meta.url),
@@ -135,8 +109,7 @@ H5 通过局域网 IP 访问时，先在仓库根目录运行 bash scripts/gener
           'node -e "import(\'@liujitcn/kratos-uni-app-core/vite\').then(({ recoverStalePageTransaction }) => recoverStalePageTransaction())"',
         'dev:h5': 'pnpm run recover:pages && uni --mode development-h5',
         'dev:mp-weixin': 'pnpm run recover:pages && uni -p mp-weixin --mode development',
-        'build:h5':
-          'pnpm run recover:pages && UNI_OUTPUT_DIR=../../../../backend/data/uni-app uni build --mode production-h5',
+        'build:h5': `pnpm run recover:pages && UNI_OUTPUT_DIR=${options.kratosProject ? '../../../../backend/data/uni-app' : 'dist/build/h5'} uni build --mode production-h5`,
         'build:mp-weixin': 'pnpm run recover:pages && uni build -p mp-weixin --mode production',
         tsc: 'vue-tsc --noEmit -p tsconfig.json',
       },
@@ -224,39 +197,6 @@ onLoad((options) => {
 })
 </script>
 <template><view /></template>
-`,
-  )
-  write(
-    target,
-    'apps/uni-app/src/main.ts',
-    `import {
-  bootstrapKratosApp,
-  initializeAppNavigation,
-  pinia,
-  registerKratosAppModules,
-  registerUserStoreExtension,
-} from '@liujitcn/kratos-uni-app-core'
-import { createSSRApp } from 'vue'
-import App from './App.vue'
-import { moduleManifest } from './module-manifest'
-
-registerKratosAppModules(moduleManifest)
-registerUserStoreExtension({
-  onLogin: initializeAppNavigation,
-  onLogout: initializeAppNavigation,
-  onSilentLogout: initializeAppNavigation,
-})
-
-export function createApp() {
-  return bootstrapKratosApp({ app: App, createSSRApp, pinia, modules: moduleManifest })
-}
-`,
-  )
-  write(
-    target,
-    'apps/uni-app/src/App.vue',
-    `<script setup lang="ts"></script>
-<style lang="scss">@use '@liujitcn/kratos-uni-app-core/styles/base.scss';</style>
 `,
   )
   write(target, 'apps/uni-app/src/uni.scss', "@forward '@liujitcn/kratos-uni-app-core/uni.scss';\n")
@@ -393,6 +333,7 @@ export default defineConfig(({ mode }) => {
           './views/*': './src/views/*',
           './package.json': './package.json',
         },
+        scripts: { build: 'pnpm pack --pack-destination ../../../dist/npm' },
         dependencies: { '@liujitcn/kratos-uni-app-core': `^${publicPackageVersion}` },
       }),
     )
@@ -427,7 +368,10 @@ packages/modules/${name}
       target,
       `packages/modules/${name}/src/index.mjs`,
       `import { defineKratosAppModule } from '@liujitcn/kratos-uni-app-core/module'
-export default defineKratosAppModule({ name: '@local/${name}', pages: {}, views: {} })
+import { LOCALE_MESSAGES } from './locales/generated.mjs'
+
+/** ${name} 业务模块，注册本地页面与语言资源。 */
+export default defineKratosAppModule({ name: '@local/${name}', pages: {}, views: {}, messages: LOCALE_MESSAGES })
 `,
     )
     write(
@@ -438,6 +382,10 @@ export default module
 `,
     )
   })
+  modules.forEach((name) => writeModuleLocales(target, name))
+  execFileSync(process.execPath, [resolve(target, 'scripts/sync-locales.mjs'), '--write'], {
+    stdio: 'inherit',
+  })
   return target
 }
 
@@ -464,6 +412,7 @@ function writeEnvironmentFiles(target) {
   )
 }
 
+/** 校验本地业务模块名称。 */
 function validateModuleName(name) {
   if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error(`模块名无效：${name}`)
 }
@@ -481,3 +430,31 @@ function write(root, file, content) {
 function json(value) {
   return `${JSON.stringify(value, null, 2)}\n`
 }
+
+/** 渲染随 CLI 发布的宿主与工具链模板。 */
+function renderWorkspaceTemplates(source, target, tokens) {
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    const input = new URL(entry.name + (entry.isDirectory() ? '/' : ''), source)
+    const output = resolve(target, entry.name)
+    if (entry.isDirectory()) {
+      mkdirSync(output, { recursive: true })
+      renderWorkspaceTemplates(input, output, tokens)
+    } else {
+      const content = Object.entries(tokens).reduce(
+        (value, [key, replacement]) => value.replaceAll(key, replacement),
+        readFileSync(input, 'utf8'),
+      )
+      writeFileSync(output, content)
+    }
+  }
+}
+
+/** 创建业务模块语言源文件及 API、RPC、测试目录，注册产物由同步命令生成。 */
+function writeModuleLocales(target, name) {
+  for (const directory of ['src/api', 'src/rpc', 'test']) {
+    write(target, `packages/modules/${name}/${directory}/.gitkeep`, '')
+  }
+  for (const locale of ['zh-CN', 'en-US', 'zh-TW', 'ja-JP']) {
+    write(target, `packages/modules/${name}/src/locales/${locale}.json`, '{}\n')
+  }
+}

package/templates/workspace/apps/uni-app/src/App.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { onHide, onLaunch, onShow } from '@dcloudio/uni-app'
+import {
+  pauseNotificationPolling,
+  resumeNotificationPolling,
+} from '@liujitcn/kratos-uni-app-system'
+
+onLaunch(() => console.log('App Launch'))
+onShow(() => resumeNotificationPolling())
+onHide(() => pauseNotificationPolling())
+</script>
+
+<style lang="scss">
+@use '@liujitcn/kratos-uni-app-core/styles/base.scss';
+</style>

package/templates/workspace/apps/uni-app/src/main.ts

@@ -0,0 +1,28 @@
+import {
+  bootstrapKratosApp,
+  initializeAppNavigation,
+  pinia,
+  registerKratosAppModules,
+  registerUserStoreExtension,
+} from '@liujitcn/kratos-uni-app-core'
+import { createSSRApp } from 'vue'
+import App from './App.vue'
+import { moduleManifest } from './module-manifest'
+import '@liujitcn/kratos-uni-app-system'
+
+registerKratosAppModules(moduleManifest)
+registerUserStoreExtension({
+  onLogin: initializeAppNavigation,
+  onLogout: initializeAppNavigation,
+  onSilentLogout: initializeAppNavigation,
+})
+
+/** 创建 uni-app 宿主实例。 */
+export function createApp() {
+  return bootstrapKratosApp({
+    app: App,
+    createSSRApp,
+    pinia,
+    modules: moduleManifest,
+  })
+}

package/templates/workspace/apps/uni-app/src/vite-env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+// 上游发布包直接导出 Vue 源文件，为生成的页面代理提供组件类型。
+declare module '@liujitcn/*.vue' {
+  import type { DefineComponent } from 'vue'
+
+  const component: DefineComponent
+  export default component
+}

package/templates/workspace/apps/uni-app/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts", "src/**/*.vue", "../../packages/modules/**/*.d.mts"]
+}

package/templates/workspace/eslint.config.mjs

@@ -0,0 +1,79 @@
+import pluginVue from 'eslint-plugin-vue'
+import prettier from '@vue/eslint-config-prettier'
+import {
+  configureVueProject,
+  defineConfigWithVueTs,
+  vueTsConfigs,
+} from '@vue/eslint-config-typescript'
+
+const projectFiles = ['**/*.{vue,js,jsx,cjs,mjs,ts,tsx,cts,mts}']
+
+configureVueProject({
+  scriptLangs: ['ts', 'js'],
+  rootDir: import.meta.dirname,
+})
+
+export default defineConfigWithVueTs(
+  {
+    ignores: [
+      'logs',
+      '*.log',
+      'npm-debug.log*',
+      'yarn-debug.log*',
+      'yarn-error.log*',
+      'pnpm-debug.log*',
+      'lerna-debug.log*',
+      'node_modules',
+      '**/dist/**',
+      '.DS_Store',
+      '*.local',
+      '.eslintrc.cjs',
+      '**/src/rpc/**',
+      // 语言注册文件由同步命令维护，避免格式化后被判为过期。
+      '**/src/locales/generated.mjs',
+      'apps/uni-app/src/pages/**',
+      '!apps/uni-app/src/pages/bootstrap/**',
+      'apps/uni-app/src/pagesMember/**',
+      'packages/core/src/module.mjs',
+      'packages/core/src/vite.mjs',
+      'packages/modules/system/src/index.mjs',
+    ],
+  },
+  pluginVue.configs['flat/essential'],
+  vueTsConfigs.recommended,
+  prettier,
+  {
+    files: projectFiles,
+    languageOptions: {
+      ecmaVersion: 'latest',
+      globals: {
+        uni: 'readonly',
+        wx: 'readonly',
+        WechatMiniprogram: 'readonly',
+        getCurrentPages: 'readonly',
+        UniApp: 'readonly',
+        UniHelper: 'readonly',
+        Page: 'readonly',
+        AnyObject: 'readonly',
+      },
+    },
+    rules: {
+      'prettier/prettier': [
+        'warn',
+        {
+          singleQuote: true,
+          semi: false,
+          printWidth: 100,
+          trailingComma: 'all',
+          endOfLine: 'auto',
+        },
+      ],
+      'vue/multi-word-component-names': 'off',
+      'vue/no-setup-props-reactivity-loss': 'off',
+      'vue/no-deprecated-html-element-is': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-empty-object-type': 'off',
+    },
+  },
+)

package/templates/workspace/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "__PROJECT_NAME__",
+  "description": "Independent pnpm workspace for __PROJECT_NAME__.",
+  "private": true,
+  "packageManager": "pnpm@10.13.1",
+  "scripts": {
+    "prepare": "pnpm run prepare:modules",
+    "prepare:modules": "pnpm --recursive --filter './packages/modules/**' --if-present run build:entries",
+    "dev:h5": "pnpm --filter @liujitcn/kratos-uni-app dev:h5",
+    "dev:mp-weixin": "pnpm --filter @liujitcn/kratos-uni-app dev:mp-weixin",
+    "build:h5": "pnpm --filter @liujitcn/kratos-uni-app build:h5",
+    "build:mp-weixin": "pnpm --filter @liujitcn/kratos-uni-app build:mp-weixin",
+    "tsc": "pnpm --recursive --if-present run tsc",
+    "test": "node --test",
+    "build:packages": "pnpm --recursive --filter './packages/modules/**' run build",
+    "check:exports": "pnpm run prepare:modules && node scripts/check-package-exports.mjs",
+    "lint": "eslint . --fix",
+    "i18n:sync": "node scripts/sync-locales.mjs --write",
+    "i18n:check": "node scripts/sync-locales.mjs"
+  },
+  "devDependencies": {
+    "@dcloudio/types": "^3.4.8",
+    "@rushstack/eslint-patch": "^1.1.4",
+    "@uni-helper/uni-app-types": "1.0.0-alpha.6",
+    "@uni-helper/uni-ui-types": "1.0.0-alpha.6",
+    "@vue/compiler-sfc": "3.4.21",
+    "@vue/eslint-config-prettier": "10.2.0",
+    "@vue/eslint-config-typescript": "14.7.0",
+    "@vue/tsconfig": "^0.7.0",
+    "eslint": "9.39.1",
+    "miniprogram-api-typings": "^4.0.5",
+    "prettier": "3.6.2",
+    "typescript": "5.4.5",
+    "vue-tsc": "^1.8.8",
+    "eslint-plugin-vue": "10.8.0",
+    "ts-proto": "^2.7.7",
+    "turbo": "^2.10.7"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "@parcel/watcher",
+      "core-js",
+      "core-js-pure",
+      "vue-demi"
+    ],
+    "auditConfig": {
+      "ignoreCves": [
+        "CVE-2024-6783"
+      ]
+    }
+  }
+}

package/templates/workspace/scripts/check-package-exports.mjs

@@ -0,0 +1,148 @@
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { dirname, extname, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const coreRoot = resolve(appRoot, 'packages/core')
+const systemRoot = resolve(appRoot, 'packages/modules/system')
+const ignoredDirectories = new Set(['dist', 'node_modules'])
+const sourceExtensions = new Set(['.js', '.mjs', '.ts', '.vue'])
+const allFiles = await collectFiles(appRoot)
+const packageFiles = allFiles.filter((file) => file.endsWith(`${sep}package.json`))
+const packages = new Map()
+const publicPackageVersions = new Map()
+const violations = []
+
+for (const packageFile of packageFiles) {
+  const metadata = JSON.parse(await readFile(packageFile, 'utf8'))
+  if (!metadata.name || !metadata.exports) continue
+  if (!metadata.private) {
+    publicPackageVersions.set(metadata.name, metadata.version)
+  }
+  const packageRoot = dirname(packageFile)
+  const exportEntries = Object.entries(metadata.exports)
+  packages.set(metadata.name, { packageRoot, exportEntries })
+  for (const [, value] of exportEntries) {
+    for (const target of collectTargets(value)) {
+      const prefix = target.includes('*') ? target.slice(0, target.indexOf('*')) : target
+      const checkPath = target.includes('*')
+        ? resolve(packageRoot, prefix)
+        : resolve(packageRoot, target)
+      if (!(await pathExists(checkPath))) {
+        throw new Error(`${metadata.name} 导出目标不存在：${target}`)
+      }
+    }
+  }
+}
+
+const distinctPublicVersions = new Set(publicPackageVersions.values())
+if (distinctPublicVersions.size > 1 || [...distinctPublicVersions].some((version) => !version)) {
+  const versions = [...publicPackageVersions]
+    .map(([name, version]) => `${name}@${version}`)
+    .join('、')
+  throw new Error(`uni-app 公开包版本必须保持一致：${versions}`)
+}
+
+for (const sourceFile of allFiles.filter((file) => sourceExtensions.has(extname(file)))) {
+  if (sourceFile.includes(`${sep}src${sep}rpc${sep}`) || isGeneratedEntry(sourceFile)) continue
+  const source = await readFile(sourceFile, 'utf8')
+  for (const imported of ts.preProcessFile(source, true, true).importedFiles) {
+    const specifier = imported.fileName
+    const line = source.slice(0, imported.pos).split('\n').length
+    if ((specifier === '@' || specifier.startsWith('@/')) && !isWithin(sourceFile, coreRoot)) {
+      violations.push(
+        `${format(sourceFile, line)}: 非 core 代码不得使用 core 私有别名 ${specifier}`,
+      )
+      continue
+    }
+    if (specifier.startsWith('@system/') && !isWithin(sourceFile, systemRoot)) {
+      violations.push(
+        `${format(sourceFile, line)}: 非 system 代码不得使用 system 私有别名 ${specifier}`,
+      )
+      continue
+    }
+    if (specifier.startsWith('.')) {
+      const sourcePackage = findPackageByPath(sourceFile)
+      const targetPackage = findPackageByPath(resolve(dirname(sourceFile), specifier))
+      if (sourcePackage && targetPackage && sourcePackage !== targetPackage) {
+        violations.push(`${format(sourceFile, line)}: 禁止通过相对路径跨包引用 ${specifier}`)
+      }
+      continue
+    }
+    const packageName = [...packages.keys()].find(
+      (name) => specifier === name || specifier.startsWith(`${name}/`),
+    )
+    if (!packageName) continue
+    const subpath = specifier === packageName ? '.' : `./${specifier.slice(packageName.length + 1)}`
+    const exported = packages
+      .get(packageName)
+      .exportEntries.some(([pattern]) => matchExportPattern(pattern, subpath))
+    if (!exported) {
+      violations.push(
+        `${format(sourceFile, line)}: ${specifier} 未在 ${packageName} exports 中公开`,
+      )
+    }
+  }
+}
+
+if (violations.length) {
+  console.error(
+    `uni-app package exports 检查失败：\n${violations.map((item) => `  ${item}`).join('\n')}`,
+  )
+  process.exit(1)
+}
+console.log(`uni-app package exports 检查通过（${[...packages.keys()].join('、')}）`)
+
+async function collectFiles(directory) {
+  const files = []
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue
+    const path = resolve(directory, entry.name)
+    if (entry.isDirectory()) files.push(...(await collectFiles(path)))
+    else files.push(path)
+  }
+  return files
+}
+
+function collectTargets(value) {
+  if (typeof value === 'string') return [value]
+  if (!value || typeof value !== 'object') return []
+  return Object.values(value).flatMap(collectTargets)
+}
+
+async function pathExists(path) {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function matchExportPattern(pattern, subpath) {
+  if (!pattern.includes('*')) return pattern === subpath
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace('\\*', '.+')
+  return new RegExp(`^${escaped}$`).test(subpath)
+}
+
+function findPackageByPath(file) {
+  return [...packages.values()].find(({ packageRoot }) => isWithin(file, packageRoot))
+}
+
+function isWithin(file, directory) {
+  const path = relative(directory, file)
+  return path === '' || (!path.startsWith('..') && !path.startsWith(sep))
+}
+
+function isGeneratedEntry(file) {
+  return (
+    file === resolve(coreRoot, 'src/module.mjs') ||
+    file === resolve(coreRoot, 'src/vite.mjs') ||
+    file === resolve(systemRoot, 'src/index.mjs')
+  )
+}
+
+function format(file, line) {
+  return `${relative(appRoot, file)}:${line}`
+}

package/templates/workspace/scripts/sync-locales.mjs

@@ -0,0 +1,46 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const modulesRoot = resolve(root, 'packages/modules')
+const write = process.argv.includes('--write')
+let expectedLocales
+for (const entry of existsSync(modulesRoot)
+  ? readdirSync(modulesRoot, { withFileTypes: true })
+  : []) {
+  if (!entry.isDirectory()) continue
+  const directory = resolve(modulesRoot, entry.name, 'src/locales')
+  const locales = readdirSync(directory)
+    .filter((file) => file.endsWith('.json'))
+    .map((file) => file.slice(0, -5))
+    .sort((a, b) => (a === 'zh-CN' ? -1 : b === 'zh-CN' ? 1 : a.localeCompare(b)))
+  if (!locales.includes('zh-CN')) throw new Error(`${entry.name} 缺少 zh-CN 语言包`)
+  if (expectedLocales && locales.join(',') !== expectedLocales)
+    throw new Error(`${entry.name} 语言集合不一致`)
+  expectedLocales = locales.join(',')
+  const messages = Object.fromEntries(
+    locales.map((locale) => {
+      if (!/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(locale))
+        throw new Error(`语言代码无效：${locale}`)
+      return [locale, JSON.parse(readFileSync(resolve(directory, `${locale}.json`), 'utf8'))]
+    }),
+  )
+  const keys = Object.keys(messages['zh-CN']).sort().join('\0')
+  for (const locale of locales) {
+    if (Object.keys(messages[locale]).sort().join('\0') !== keys)
+      throw new Error(`${entry.name}/${locale} 语言键集合不一致`)
+  }
+  // 模块在 Vite 配置阶段由 Node 直接加载，使用无需 TS/JSON loader 的原生 ESM。
+  const content = [
+    '/* 此文件由 scripts/sync-locales.mjs 生成，请勿手工修改。 */',
+    `export const LOCALE_MESSAGES = ${JSON.stringify(messages, null, 2)}`,
+    "export const DEFAULT_LOCALE = 'zh-CN'",
+    'export const SUPPORTED_LOCALES = Object.keys(LOCALE_MESSAGES)',
+    '',
+  ].join('\n')
+  const file = resolve(directory, 'generated.mjs')
+  if (write) writeFileSync(file, content)
+  else if (!existsSync(file) || readFileSync(file, 'utf8') !== content)
+    throw new Error(`语言注册产物过期：${file}，请执行 pnpm i18n:sync`)
+}