替换落地页和定价页
重写示例首页、用 page-shell 原语新增公开页面,并了解 /pricing 读取什么数据、校验器强制哪些规则。
底座在 / 提供了一个示例落地页,页面文案已注明它需要改写。/pricing 是实际可用的页面,列出结账时收费的套餐。本指南说明如何重写落地页,以及 /pricing 读取哪些数据。
准备工作
- 一个能用
pnpm dev跑起来的项目,并且src/config/site.ts里已经是你的名称。见换成自己的品牌。 - 首页在每种上线语言下的文案。默认英文和中文都必须提供,见新增与修改文案。
- 对于
/pricing:至少一个处于上架状态的套餐。见定价套餐。
认识各个部件
| 部件 | 文件 | 说明 |
|---|---|---|
| 首页路由 | src/routes/{-$locale}/index.tsx | 加载会话快照,为 / 和 /zh 渲染 ExampleLandingPage |
| 落地页组件 | src/components/marketing/example-landing.tsx | ExampleLandingPage、buildHomeHead 和 loadHomeRouteData |
| 落地页文案 | 两份 messages.ts 中的 publicSite.landing | 标题、导语、两个行动按钮、features、steps 和结尾区块 |
| 公开站外壳 | src/components/marketing/public-shell.tsx | PublicMarketingShell(页头、页脚、跳转链接)和 PublicPageHero |
| 布局原语 | src/components/marketing/ui/page-shell.tsx | Section、SectionHeader、Panel、PanelGrid、Eyebrow、PageTitle、ArrowLink、Screenshot、CommandLine、FactList、PageContainer |
| 定价页 | src/components/marketing/pricing-plans-page.tsx | PricingPlansPage,由 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" 只用于唯一的结尾区块。
<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,这样这些页面保持匿名,可以缓存。
新增一个公开页面
- 在两份
messages.ts中新增一个命名空间存放文案,写法参考aboutPage。 - 在
src/components/marketing/localized-pages.tsx中AboutMarketingPage旁边新增组件(也可以在src/components/marketing/下单独建文件):PublicMarketingShell包住一个PublicPageHero和一个或多个Section。 - 复制
src/routes/{-$locale}/about.tsx作为新路由,修改createFileRoute("/{-$locale}/about")里的路径。 - 把路径加入
src/server/services/static-seo.service.ts的publicSeoRoutes,它才会出现在/sitemap.xml中。 - 需要放进页头时,在
src/components/marketing/public-shell.tsx的publicNavigation中加一项,并在两份字典的publicSite.navigation下加上对应的标签。页脚链接也在这个文件里。 - 运行一次
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。