换成自己的品牌
把 Kernlift 的名称、域名、描述、图标和分享图换成你自己的,并决定用户登录后落在哪个页面。
新建的项目在页头、浏览器标签、邮件和分享卡片里仍然写着 Kernlift。站点身份在 src/config/site.ts 一个文件里设置。本指南还说明这个文件不涉及的几处:消息字典里的页面标题、生成的图标素材,以及发件人名称。
准备工作
- 一个能用
pnpm dev在本地运行的项目。见快速开始。 - 产品名称、一句话描述和生产域名。
- 可选:自己的 SVG 标志,以及一张 1200×630 的分享图。
设置站点身份
编辑 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、backgroundColor | theme-color meta 标签和 manifest |
twitter.site | twitter:site;留空则不输出该标签 |
刚克隆的仓库里,name、shortName 和 url 还是模板自己的,三项都要改。
设置生产域名
SITE_URL 会在运行时覆盖 siteConfig.url,因此同一份构建既能服务预览域名,也能服务生产域名。在应用运行的环境里设置它:
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.ico | 32×32 | 不支持 SVG 图标的浏览器 |
public/apple-touch-icon.png | 180×180 | iOS 主屏幕 |
public/icon-192.png、public/icon-512.png | 192×192、512×512 | web manifest |
public/og-default.png | 1200×630 | 默认分享图 |
之后再运行 pnpm assets:generate 会覆盖这些文件。
让浏览器外框颜色与配色一致
把 site.ts 里的 themeColor 和 backgroundColor 设为你的主色和页面底色。它们是普通的十六进制字符串,不会自动跟随 CSS 令牌。如果你改了 --primary 或 --background,这里也要一起改。见使用设计系统。
检查元数据和站点地图
页面通过 src/lib/seo.ts 中的 buildMeta() 生成 <head>,页面没有提供的字段会回退到站点配置。需要你维护的只有两份清单:
- 打开
src/server/services/static-seo.service.ts,编辑publicSeoRoutes:删掉已经移除的页面,加上新建的公开页面。/sitemap.xml会把这份清单按每种语言各渲染一遍,并带上hreflang互链。 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 会失败。