应用配置

深入理解 src/config/index.ts：每个配置项的作用、影响范围与改动建议。

src/config/index.ts 是 MuseMVP 的运行时总配置入口，集中管理 i18n、认证行为、存储、支付与统计。
如果你要“改产品行为”，通常第一站就是这个文件。

本页关注点

本页只讲 src/config/index.ts 的代码级配置。启动密钥（数据库、OAuth、邮件、MUSE_SETTINGS_SECRET）见 /docs/quick-build/environment-variables。支付网关和 S3 凭证不是环境变量——在运行时设置填写。

配置指南

i18n：国际化

关键字段：

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

实际影响：

docsAlias 用于文档页面标题后缀（例如 xxx | 文档）。
页头/页脚文案在 home.json，不在这份 locale 配置里。
localePrefix 会影响 next-intl 路由行为与 docs source 的语言隐藏策略。

改文案时的建议

en 和 zh 同步修改，避免导航与页脚双语不一致。

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。

容易误解的点

allowTwoFactorAuth 不是后端插件总开关。2FA 插件仍会注册，它主要影响前端是否暴露入口。

mails：邮件发件人和品牌 Logo

关键字段：

mails.from
mails.links.logo

行为要点：

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

ui：主题、SaaS 壳与联系表单投递

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

ui: {
  enabledThemes: ["light", "dark", "system"],
  defaultTheme: "light",
  saas: { enabled: true, cookieInfo: { showBox: false } },
  contactForm: {
    to: "[email protected]",
    subject: "MuseMVP contact form message",
  },
}

行为要点：

ui.saas.enabled=false 会关闭 auth 区域和 saas 区域入口（相关 layout 会直接重定向到首页）。
登录后壳层在 src/modules/layout/。见应用布局自定义。
contactForm.to / subject 是联系表单的投递地址和主题，不会隐藏 /contact。
页头/页脚链接不是配置开关。请改 SwitchHeader、SwitchFooter、site-links.ts 和 home.json。
文档、博客、法律页、功能页、更新日志、联系页默认可访问；隐藏它们请删导航链接，必要时再删路由文件。

没有页面开关矩阵

没有 ui.docs.enabled、ui.blog.enabled、ui.legal.allowMap、headerConfig 或 footerConfig。隐藏公开页就是在 header/footer 组件里删掉对应链接。

storage：Cloudflare R2

S3 凭证与头像 bucket 在 后台 → 运行时设置，不在 config/index.ts。

仍留在 config 的字段：

storage.proxyUrls.avatarsFile（来自 NEXT_PUBLIC_AVATARS_PROXY_URL）

行为要点：

上传接口检查数据库中的 S3 凭证；缺失会返回 STORAGE_ENV_MISSING。
NEXT_PUBLIC_AVATARS_PROXY_URL 仍在环境变量里，因为客户端组件在浏览器拼接头像 URL。会去掉末尾 / 再参与拼接。

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

关键字段：

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

productCatalog 使用稳定的套餐 ID（pro_monthly、pro_yearly、lifetime）给公开定价页和结账请求。支付商产品 ID 来自后台运行时设置（billing.productMap）。

行为要点：

结账使用后台产品映射；缺失会抛出可读错误。
pricing-desc-usage.ts 还支持可选字段 originalAmount，用于展示划线原价；它只影响定价 UI，实际结算仍使用 amount。
enableBilling=false 会关闭定价入口与相关计费流程分支。 /pricing 会重定向到首页。首页的 PricingSection 返回 null。首页区块顺序是 (home)/page.tsx 里的 JSX 列表，不是配置里的开关对象。