应用配置

i18n：国际化

关键字段：

• i18n.enabled
• i18n.locales.en|zh（appName/summary/description/keywords/docsAlias/headerMenuMap/footerConfig）
• i18n.defaultLocale
• i18n.defaultCurrency
• i18n.localePrefix
• i18n.localeCookieName

实际影响：

• docsAlias 用于文档页面标题后缀（例如 xxx | 文档）。
• headerMenuMap 会被导航和自定义路由复用。
• localePrefix 会影响 next-intl 路由行为与 docs source 的语言隐藏策略。

users：新用户注册引导页以及计费总开关

关键字段：

• users.enableSetup

当前行为：

• enableSetup=true：新注册用户（未完成 onboarding 的登录用户）会被引导到引导页 /setup。

auth：注册方式与会话生命周期

关键字段：

• auth.gates.allowRegister
• auth.gates.allowSocialSignIn
• auth.gates.allowPasswordSignIn
• auth.gates.allowTwoFactorAuth
• auth.lifecycle.redirectAfterLogin
• auth.lifecycle.redirectAfterSignOut
• auth.lifecycle.redirectWhenSessionExpired
• auth.lifecycle.sessionTtlSeconds

行为要点：

• allowRegister=false 时，/auth/register 会重定向到 /auth/login。
• allowPasswordSignIn 和 allowSocialSignIn 主要控制前端入口显示。
• allowTwoFactorAuth 主要控制设置页的 2FA 区块显示。
• sessionTtlSeconds 会直接写入 Better-Auth 的 session.expiresIn。

mails：邮件发件人和品牌 Logo

关键字段：

• mails.from
• mails.links.logo

行为要点：

• mails.from 如果只写邮箱地址，会在发送时自动组装为 "AppName" <email@...> 格式。
• mails.links.logo 用于邮件模板中的LOGO，默认使用项目根目录下的 public/icon.png，你也可以使用自定义访问速度更快的图片的外链。

ui：主题、页面开关、导航与页脚

ui 是改动频率最高的一段，建议分块理解。

ui: {
  enabledThemes: ["light", "dark"],
  defaultTheme: "dark",
  saas: { enabled: true, useSidebarLayout: true, cookieInfo: { showBox: true } },
  features: { enabled: true },
  docs: { enabled: true },
  legal: {
    enabled: true,
    allowMap: [
      { type: "privacy", enabled: true },
      { type: "terms", enabled: true },
      { type: "behavior", enabled: false },
    ],
  },
  changelog: { enabled: true },
  blog: { enabled: true },
  contactForm: {
    enabled: true,
    to: "support@musemvp.com",
    subject: "MuseMVP contact form message",
  },
}

行为要点：

• ui.saas.enabled=false 会关闭 auth 区域和 saas 区域入口（相关 layout 会直接重定向到首页）。
• ui.docs/blog/changelog/contactForm/features 会同时影响导航显示与对应页面访问。
• ui.legal.enabled 控制 legal 页面总开关；allowMap 主要影响页脚/认证页的法律链接展示。
• customRoutes 为 enabled && !external 的项目会自动进入 sitemap。
• customRoutes 的最终标题优先取 headerMenuMap[path]，其次 label。
• footerConfig.socialIcon.github.href 还会被文档页用于生成 GitHub 源码链接。

storage：Cloudflare R2

关键字段：

• storage.meta.S3_ACCESS_KEY_ID
• storage.meta.S3_SECRET_ACCESS_KEY
• storage.meta.S3_ENDPOINT
• storage.meta.S3_REGION（默认 auto）
• storage.bucketNames.avatars（默认 musemvp-com）
• storage.proxyUrls.avatarsFile

行为要点：

• 上传接口会检查 S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY / S3_ENDPOINT，缺失会返回错误。
• NEXT_PUBLIC_AVATARS_PROXY_URL 会去掉末尾 / 再参与拼接。
• avatars 桶名不配时会回退到默认值 musemvp-com。

ai：聊天模型选择

关键字段：

• ai.enabled
• ai.chatModel

行为要点：

• ai.enabled=false 时，会隐藏账号后台中的 AI Chat 导航项，/app/aichat 重定向到 /app，并让 /api/aichat/** 返回 404。
• 后端 AI Chat 路由直接读取 config.ai.chatModel 作为 MODEL_ID ，默认模型 gemini-3-pro-preview。
• 更换模型通常只需改这一处（前提是对应 provider key 已配置）。

payments：计费总开关与产品目录映射

关键字段：

• payments.enableBilling
• payments.enableFree
• payments.enableEnterprise
• payments.productCatalog

productCatalog 的 productId 读取优先级（以月付 Pro 为例）：

NEXT_PUBLIC_MUSE_PRICE_PRO_MONTHLY_ID
  -> NEXT_PUBLIC_MUSE_CREEM_PRICE_PRO_MONTHLY_ID
  -> NEXT_PUBLIC_MUSE_STRIPE_PRICE_PRO_MONTHLY_ID
  -> ""

行为要点：

• productCatalog.*.gatewayProductIds 会在发起 checkout 时使用；缺失会直接报错。
• pricing-desc-usage.ts 里只有 productId 非空的价格项才会进入套餐展示。
• pricing-desc-usage.ts 还支持可选字段 originalAmount，用于展示划线原价；它只影响定价 UI，实际结算仍使用 amount。
• enableBilling=false 会关闭定价入口与相关计费流程分支。

analytics：统计脚本注入

关键字段：

• analytics.googleAnalyticsId
• analytics.baiduTongjiId

行为要点：

• 统计脚本只在非 development 环境注入。
• ID 为空时对应脚本不会渲染。

Header / Footer 文案是否在 en 与 zh 下都正常显示。

docs/blog/legal/changelog/contact/features 的可见性是否符合开关预期。

若 ai.enabled=false，确认 AI Chat 已从侧边栏和个人菜单中隐藏，/app/aichat 会重定向，且 /api/aichat/** 不可访问。

登录、注册、退出后的跳转是否符合 auth.lifecycle 配置。

定价页是否只展示已配置 productId 的套餐项。

如果配置了 originalAmount，确认定价卡片会显示划线原价，同时 checkout 仍按 amount 发起结算。

上传头像与资源访问是否符合 storage 配置（桶名/代理地址）。