替换落地页和定价页

重写示例首页、用 page-shell 原语新增公开页面,并了解 /pricing 读取什么数据、校验器强制哪些规则。

底座在 / 提供了一个示例落地页,页面文案已注明它需要改写。/pricing 是实际可用的页面,列出结账时收费的套餐。本指南说明如何重写落地页,以及 /pricing 读取哪些数据。

准备工作

  • 一个能用 pnpm dev 跑起来的项目,并且 src/config/site.ts 里已经是你的名称。见换成自己的品牌。
  • 首页在每种上线语言下的文案。默认英文和中文都必须提供,见新增与修改文案。
  • 对于 /pricing:至少一个处于上架状态的套餐。见定价套餐。

认识各个部件

部件文件说明
首页路由src/routes/{-$locale}/index.tsx加载会话快照,为 / 和 /zh 渲染 ExampleLandingPage
落地页组件src/components/marketing/example-landing.tsxExampleLandingPage、buildHomeHead 和 loadHomeRouteData
落地页文案两份 messages.ts 中的 publicSite.landing标题、导语、两个行动按钮、features、steps 和结尾区块
公开站外壳src/components/marketing/public-shell.tsxPublicMarketingShell(页头、页脚、跳转链接)和 PublicPageHero
布局原语src/components/marketing/ui/page-shell.tsxSection、SectionHeader、Panel、PanelGrid、Eyebrow、PageTitle、ArrowLink、Screenshot、CommandLine、FactList、PageContainer
定价页src/components/marketing/pricing-plans-page.tsxPricingPlansPage,由 src/routes/{-$locale}/pricing.tsx 渲染
关于与联系src/components/marketing/localized-pages.tsx两个用同样方式搭建的短页面,新增页面时可以照抄

重写首页

先改文案

修改 src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts 中的 publicSite.landing。如果现有结构(首屏、功能网格、三个步骤、结尾行动按钮)适合你的产品,改完这些字符串就完成了。页面的 <title> 和分享卡片在同一文件的 seo.home.title、seo.home.description 中设置。

在 example-landing.tsx 中调整布局

用原语拼出一个个区块。Section 是一条通栏区块。tone="stage" 使用柔和的背景色,区块在 page 与 stage 之间交替。tone="inverted" 只用于唯一的结尾区块。

src/components/marketing/example-landing.tsx
<PublicMarketingShell locale={locale}>
  <PublicPageHero
    actions={
      <ButtonLink href={localizedPath("/auth/sign-up", locale)} variant="primary">
        {copy.primaryCta}
      </ButtonLink>
    }
    copy={copy.copy}
    eyebrow={siteConfig.name}
    title={copy.title}
  />
  <Section tone="stage">
    <div className="grid min-w-0 gap-8">
      <SectionHeader eyebrow={copy.featuresEyebrow} title={copy.featuresTitle} />
      <PanelGrid columns={3}>
        {copy.features.map((feature) => (
          <Panel key={feature.title}>
            <h3 className="m-0 text-base leading-6 font-semibold">{feature.title}</h3>
            <p className="m-0 text-sm leading-6 text-muted-foreground">{feature.body}</p>
          </Panel>
        ))}
      </PanelGrid>
    </div>
  </Section>
</PublicMarketingShell>

按钮来自 @/components/motion/button(Button、ButtonLink)。站内链接一律用 localizedPath(path, locale) 生成,这样 /zh 页面只会链接到 /zh 页面。样式用基于产品令牌的 Tailwind 工具类(text-muted-foreground、border-border、bg-card),见使用设计系统。

保留文件、导出名和两个链接

有几个校验器会读取这个页面。满足以下条件它们就保持通过:

  • 组件仍在 src/components/marketing/example-landing.tsx 中,以 ExampleLandingPage 导出,loadHomeRouteData 与它同文件,首页路由仍然渲染它;
  • 文案通过 getMessageNamespace(locale, "publicSite").landing 读取;
  • 页面上保留一个指向 /auth/sign-up 的链接和一个指向 /pricing 的链接;
  • 渲染站点名称、title、primaryCta、secondaryCta、每个 features[].title 和 steps 的每一项。

如果你的设计不再需要功能网格或步骤,就在同一次改动里从两份字典中删掉这些键,并更新 scripts/validate/example-landing.ts 里的期望列表。不要让校验器断言页面已经不再渲染的文案。

为已登录的访客显示账户入口

首页是唯一会加载会话的公开页面。loadHomeRouteData() 返回当前用户、是否可以进入 /admin 以及积分余额。ExampleLandingPage 把 PublicAccountMenu 传给外壳的 account 属性,替换掉登录和注册按钮。其他公开页面不要设置 account,这样这些页面保持匿名,可以缓存。

新增一个公开页面

  1. 在两份 messages.ts 中新增一个命名空间存放文案,写法参考 aboutPage。
  2. 在 src/components/marketing/localized-pages.tsx 中 AboutMarketingPage 旁边新增组件(也可以在 src/components/marketing/ 下单独建文件):PublicMarketingShell 包住一个 PublicPageHero 和一个或多个 Section。
  3. 复制 src/routes/{-$locale}/about.tsx 作为新路由,修改 createFileRoute("/{-$locale}/about") 里的路径。
  4. 把路径加入 src/server/services/static-seo.service.ts 的 publicSeoRoutes,它才会出现在 /sitemap.xml 中。
  5. 需要放进页头时,在 src/components/marketing/public-shell.tsx 的 publicNavigation 中加一项,并在两份字典的 publicSite.navigation 下加上对应的标签。页脚链接也在这个文件里。
  6. 运行一次 pnpm dev,让 src/routeTree.gen.ts 收录新路由。

了解 /pricing 读取什么

/pricing 的代码里没有任何套餐数据。它的 loader 按当前语言调用 getMarketingSite(),只保留状态为 active 的套餐。这些记录来自 pricing_plans 表,每个套餐每种语言一行,在 /admin/plans 中编辑。

页面上的内容来源
套餐名称、描述、功能列表、按钮文字该套餐在当前语言下的那一行
价格该行的 priceCents 和 currency,按语言格式化
计费周期publicSite.pricing.intervals(month、year、lifetime、one_time)
「包含积分」一行includedCredits,大于零时显示
标题、导语、空状态字典中的 publicSite.pricing

套餐按钮向 /api/billing/checkout 发起请求。服务端重新计算价格,再把浏览器跳转到支付服务商的结账页。未登录的访客先跳到登录页,登录后回到 /pricing。其他失败跳到 /system/payment-failed,并附带原因。已登录用户在 /app/billing/upgrade 看到的是同一批套餐。

要调整售卖内容,在后台修改套餐。要调整页面样式,可以修改 PricingPlansPage,但必须保留 requestCheckout() 作为按钮发起购买的唯一途径。没有上架套餐时,页面只显示 publicSite.pricing.empty 这句文案。

遵守校验器强制的规则

pnpm validate:example-landing 会读取 example-landing.tsx 和 pricing-plans-page.tsx,出现以下任一情况即失败:

  • 从 src/components/ui(shadcn)导入;
  • 硬编码颜色(#hex、rgb( 或 hsl();
  • 使用 ds-、mk- 或 ds-mk- 前缀的类名。ds-mk-* 营销命名空间已经停用,不要再引入,也不要沿用设计生成工具产出的类名;
  • 使用内联的 style={{ … }};
  • 没有渲染在 PublicMarketingShell 里。

公开页面不声明自己的令牌。缺少某个颜色时,在 src/styles/app.css 的 :root 上新增或修改令牌,这样所有界面都能使用。这个校验器还会检查落地页、定价页和外壳渲染出的每个链接,以及 publicSeoRoutes 中的每个路径,只要有一个找不到对应的路由文件就失败。

验证

pnpm validate:example-landing
pnpm validate:marketing
pnpm validate:route-i18n
pnpm validate:app-i18n
pnpm validate:mobile

然后在浅色和深色主题、手机宽度和桌面宽度下分别打开 / 和 /zh。未登录时打开 /pricing 并点击某个套餐。页面先跳到登录页,登录后回到 /pricing。

下一步