换成自己的品牌

把 Kernlift 的名称、域名、描述、图标和分享图换成你自己的,并决定用户登录后落在哪个页面。

新建的项目在页头、浏览器标签、邮件和分享卡片里仍然写着 Kernlift。站点身份在 src/config/site.ts 一个文件里设置。本指南还说明这个文件不涉及的几处:消息字典里的页面标题、生成的图标素材,以及发件人名称。

准备工作

  • 一个能用 pnpm dev 在本地运行的项目。见快速开始。
  • 产品名称、一句话描述和生产域名。
  • 可选:自己的 SVG 标志,以及一张 1200×630 的分享图。

设置站点身份

编辑 src/config/site.ts

src/config/site.ts
export const siteConfig = {
  name: "Acme",
  shortName: "Acme",
  url: normalizeOrigin(process.env.SITE_URL ?? "https://acme.com"),
  description: "One sentence that says what Acme does.",
  ogImage: "/og-default.png",
  locale: "en",
  themeColor: "#3859D6",
  backgroundColor: "#F6F5F1",
  twitter: { site: "", card: "summary_large_image" },
} as const;
字段用在哪里
name公开站页头与页脚、登录注册页、工作台侧边栏、系统页、邮件外壳、og:site_name、订阅源标题和 web manifest
shortName/manifest.webmanifest 中的 short_name
url规范链接、og:url、站点地图、robots.txt、订阅源,以及邮件里的绝对链接
description兜底的 meta description、订阅源和 manifest
ogImage兜底的 og:image 与 twitter:image,相对于 url
themeColor、backgroundColortheme-color meta 标签和 manifest
twitter.sitetwitter:site;留空则不输出该标签

刚克隆的仓库里,name、shortName 和 url 还是模板自己的,三项都要改。

设置生产域名

SITE_URL 会在运行时覆盖 siteConfig.url,因此同一份构建既能服务预览域名,也能服务生产域名。在应用运行的环境里设置它:

.env
SITE_URL=https://acme.com

结尾不需要斜杠,配置会自动去掉。OAuth 回调和认证邮件里的链接使用 /admin/config/auth 里的 基础 URL。首次启动时它用站点地址初始化,域名变化时在那里修改。见环境变量。

替换两份字典里的默认标题

全站默认标题和首页标题属于文案,所以放在消息字典里,而不在 site.ts。在 src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts 中修改相同的键:

键出现位置
seo.default.title、seo.default.description根文档输出的兜底标题和描述
seo.home.title、seo.home.description首页
content.blogCopy博客列表页的导语(安装 CMS 模块时)

文案的组织方式见新增与修改文案。

替换图标和分享图

选择生成素材还是手工素材

项目自带的占位素材由脚本绘制。你可以保留生成器,把名称和配色换成自己的,也可以直接放入自己的文件。

要重新生成,先修改 scripts/assets/generate-site-assets.ts 顶部的常量(siteName、tagline 和 palette),然后运行:

pnpm assets:generate

它会重写 public/ 下的 favicon.svg、favicon.ico、apple-touch-icon.png、icon-192.png、icon-512.png 和 og-default.png,以及 public/placeholder/ 下的图片。

或者手工替换文件

保持以下文件名和尺寸不变,因为根文档、manifest 和各个外壳都按路径引用它们:

文件尺寸用途
public/favicon.svg矢量浏览器标签,以及公开站页头、登录页和系统页里的标志
public/favicon.ico32×32不支持 SVG 图标的浏览器
public/apple-touch-icon.png180×180iOS 主屏幕
public/icon-192.png、public/icon-512.png192×192、512×512web manifest
public/og-default.png1200×630默认分享图

之后再运行 pnpm assets:generate 会覆盖这些文件。

让浏览器外框颜色与配色一致

把 site.ts 里的 themeColor 和 backgroundColor 设为你的主色和页面底色。它们是普通的十六进制字符串,不会自动跟随 CSS 令牌。如果你改了 --primary 或 --background,这里也要一起改。见使用设计系统。

检查元数据和站点地图

页面通过 src/lib/seo.ts 中的 buildMeta() 生成 <head>,页面没有提供的字段会回退到站点配置。需要你维护的只有两份清单:

  1. 打开 src/server/services/static-seo.service.ts,编辑 publicSeoRoutes:删掉已经移除的页面,加上新建的公开页面。/sitemap.xml 会把这份清单按每种语言各渲染一遍,并带上 hreflang 互链。
  2. robots.txt 一般不用动,除非你新增了别的私有区域。它由 src/routes/robots[.]txt.ts 输出,已经禁止抓取 /admin、/app 和 /api,并指向当前配置域名下的站点地图。

不要新增 public/sitemap.xml。它会遮住路由,pnpm validate:site-metadata 也会失败。

设置发件人名称

邮件外壳里的产品名取自 site.ts,但发件人是一项存储在数据库里的设置。打开设置 → 邮件配置(/admin/config/email),把发件人地址改成你自己的名称和已验证的域名。见发送事务邮件。

决定登录后落在哪里

从受保护页面跳去登录的访客,会通过 redirectTo 参数回到原页面。没有这个参数时,落在 src/config/site.ts 的 signedInHome,默认是 /app/profile。邮箱登录、注册、社交登录以及邮箱验证成功后的按钮都读取它。

signedInHome: "/app",

填写 /app 下不带语言前缀的站内相对路径。语言前缀会按访客的语言自动加上,登录页只接受 /auth 之外的相对路径。

验证

pnpm validate:site-metadata
pnpm validate:example-landing
pnpm typecheck

然后启动 pnpm dev 检查:

  • 页头、浏览器标签和 /auth/sign-in 显示你的名称和标志。
  • /manifest.webmanifest 返回你的 name、short_name 和颜色。
  • 设置 SITE_URL 后,/sitemap.xml 和 /robots.txt 使用你的域名。
  • 查看 / 的页面源码:og:title、og:image 和规范链接都是你的名称和域名。
  • 退出后重新登录:落在你选定的页面。

图标缺失、源码引用了 public/ 中不存在的图片,或某个页面绕过 buildMeta() 自己写规范链接时,pnpm validate:site-metadata 会失败。

下一步