tootaio.com/docs/20251106/architecture.md

架构结构与改进方案

本文审计 Nuxt 4.2.0 架构与模块使用，指出结构异味并提供可落地改进。

现状评估

• 模块与目录（Low）
  • app/（pages/layouts/composables/utils/assets）职责清晰。
  • content/ 与 content.config.ts 使用 zod 定义 Schema，利于类型驱动内容。
  • i18n/ 采用 locales/<locale> 结构；no_prefix 策略与当前站点定位一致。
• Nuxt 4 特性使用（Medium）
  • 自动导入：已使用（如 useLocalizedCollection）。建议将文件命名统一为 useXxx.ts 便于识别。
  • Runtime Config：未使用。建议引入 runtimeConfig 管理外部域名、监控 DSN 等。
  • Nitro Route Rules/缓存：未配置。建议为首页与静态资源设置 prerender+swr 与长缓存。
• 设计风险（Critical）
  • content.config.ts 的 Index Schema 与 YAML 不一致：缺少 title/description/seo 字段；icon/highlight/spotlight 约束与内容不符。

改进策略

1. 内容 Schema 对齐（Critical）
   • 为 Index 增加 title/description/seo；将 icon 设为可选，将 highlight/spotlight 设为可选并默认 false。
   • 参见补丁：0001-content-config-align.patch。
2. 运行时配置（Medium）
   • 在 nuxt.config.ts 中：

     export default defineNuxtConfig({
       runtimeConfig: {
         sentryDsn: '',
         public: { assetBase: 'https://img.tootaio.com' },
       },
     })
     

   • 在代码中读取 useRuntimeConfig()，避免硬编码外链与密钥。
3. 路由规则与缓存（Medium）
   • 为首页预渲染并设置 SWR，为构建产物设置 immutable 缓存：

     export default defineNuxtConfig({
       routeRules: {
         '/': { prerender: true, swr: 3600 },
         '/_nuxt/**': {
           headers: { 'cache-control': 'public, max-age=31536000, immutable' },
         },
       },
     })
     

   • 参见补丁：0004-nuxt-route-rules.patch。
4. 组合式命名与分层（Low）
   • 将 app/composables/LocalizedCollection.ts 重命名为 useLocalizedCollection.ts。
   • 保持 composable 只做“取数+组装”，复杂 UI/状态拆到组件/Pinia（若引入）。

与 Nuxt 4.2.0 兼容性

• 现有 compatibilityDate: '2025-07-15' 符合要求。
• 上述配置属于稳定 API：routeRules/runtimeConfig/auto-import，安全可用。