freehire 品牌化 OG 卡片体系:静态品牌图、企业分享卡与共享渲染原语
freehire 品牌化 OG 卡片体系:静态品牌图、企业分享卡与共享渲染原语
本文以 freehire 仓库中 og-brand-cards 变更提案为主线,讲清一件事:如何用一套纯前端(SvelteKit)的实现,让站内每一个页面在社交平台和即时通讯工具里都拥有一张 1200×630 的品牌化链接预览图,并为企业详情页额外提供按需渲染的定制卡片。读完后你可以掌握三层图像解析策略、satori + resvg 的渲染管线、卡片共享原语的抽取方式,以及静态品牌图的生成与再生成流程。
变更背景:只有职位详情页有预览图
提案开篇指出了具体问题:freehire 当时已经有一条“每个职位一张 OG 图”的流水线,GET /jobs/:slug/og.png 由 satori 渲染成 PNG;但 Seo.svelte 只会在页面显式传入 image 属性时输出 og:image,而全站只有职位详情页这么做。
于是 /、/companies/*、/b/* 以及各类营销页被分享出去时,只剩一张纯文本卡片。企业详情页尤其可惜——企业 logo 本身是辨识度极高的视觉资产,却没有被用于预览。
提案对这个现状的定性很克制:这不是“缺少功能”,而是已有的 OG 能力没有被默认化和复用。因此变更被明确界定为纯前端改动,不触碰 Go 后端、数据库和 API:
| 维度 | 结论 |
|---|---|
| 影响范围 | 仅 web/(SvelteKit),无 Go/backend/DB/API 变更 |
| 新增能力 | og-brand-image(静态品牌图 + 全站默认 og:image)、company-og-images(企业按需预览图) |
| 复用资产 | satori/resvg 渲染核心、resolveLogo、loadOgFonts、countryLabel、og-smoke.mjs 校验模式 |
| 明确不做 | 不做动态首页 OG 端点;不用 emoji 国旗;不改职位卡的规格级行为 |
三层图像解析策略:后一层覆盖前一层
设计文档给出的核心决策是“三层图像,逐层覆盖”,没有任何注册表或配置开关,层级选择就是页面传给 <Seo> 的 image 值:
- 静态品牌 PNG(站点默认)——web/static/og.png,通过
/og.png提供,未传image的页面全部落到这里; - 职位卡——
/jobs/:slug/og.png,变更前已存在; - 企业卡——
/companies/:slug/og.png,本次新增。
设计文档同时记录了被否决的备选方案:做一个动态 /og.png 端点、请求时读取实时统计。否决理由是品牌卡本质上是固定内容——标题固定、数字只是量级展示——用一张提交进仓库的 PNG 更简单,且请求时零成本。这一点区分了“静态品牌卡”和“职位卡/企业卡”:后两者必须实时,因为它们描述的是会变化的实体。
共享原语:让三种卡片说同一种品牌语言
变更的第二个关键决策是把此前塞在 card.ts 里的品牌构件抽到 shared.ts。文件头部注释直接写明了目的:纯函数、不依赖框架,使每张卡片共用一套品牌词汇,从而“cannot drift”(不可能漂移),同时让渲染冒烟测试可以直接调用它们。
抽出的成员与职责:
| 导出 | 作用 | 关键实现细节 |
|---|---|---|
OG_WIDTH / OG_HEIGHT |
画布尺寸常量 | 固定 1200×630(L8-L9) |
MARK_DATA_URI |
freehire 品牌标记 | 内联 SVG 的 base64 data-URI,填充色 #0a0a0a,satori 无法抓取远程图片,必须内联(L14-L18) |
esc |
HTML 转义 | 转义 & < > ",所有插值文本必须先过一遍 |
monogram |
单/双字母首字母 | 无 logo 时取名称前两个词首字母,单词则取前两个字符,全大写;空名回退 ? |
logoBox(logo, name, size, shape) |
参数化 logo 瓦片 | 半径、字号随尺寸等比缩放;tile 用 contain,circle 用 cover |
Chip / chipMarkup |
胶囊标签 | muted 变体用于“+N”这类弱化信息,无色块 |
brandFooter() |
统一页脚 | 左侧 mark + freehire 字标,右侧 freehire.me 域名 |
logoBox 是一个值得单独说的设计点。它把“尺寸”变成了唯一变量:圆角用 size / 5,字母字号用 size * 0.42,所以同一套代码能在 72px(原始职位卡尺寸)、96px(本次放大后的职位卡)、140px(企业卡主视觉)、160px(贡献者头像)下保持视觉比例一致,而无需为每个尺寸手写样式。
它还用 shape 参数承载了设计系统 Avatar 里已有的语义区分:圆角瓦片代表“实体”,圆形代表“人”。注释写得很直白——一张关于人的卡片如果把人裁成方块,读起来就像一个公司 logo。这一点在后续的贡献者卡片中被复用(contributor.ts 传入 'circle')。
satori 的硬约束:只有 flexbox
共享模块与三张卡片都以注释形式重复了同一条约束:satori 只支持 flexbox 布局,没有 CSS grid;任何拥有多个子元素的节点都必须声明 display:flex。这就是为什么你会看到大量 display:flex;flex-direction:column 包裹层——它们不是冗余,而是 satori 渲染正常工作的前提。
设计文档把这条约束列为风险项,并给出了对应的缓解方式:让 og-smoke 与 gen-og 真实渲染每一种卡片,从而在 CI 式的脚本执行中直接暴露违规,而不是等到线上分享时才发现图是空白。
渲染原语:一个 renderMarkupPng 覆盖所有卡片
变更前,render.ts 只认识 Job 类型。任务清单 2.1 要求把它泛化:
// web/src/lib/server/og/render.ts
export async function renderMarkupPng(markup: string, fonts: OgFont[]): Promise<Uint8Array<ArrayBuffer>> {
const svg = await satori(html(markup), { width: OG_WIDTH, height: OG_HEIGHT, fonts });
const png = new Resvg(svg, { fitTo: { mode: 'width', value: OG_WIDTH } }).render().asPng();
const out = new Uint8Array(png.byteLength);
out.set(png);
return out;
}
三步不变:satori-html 把 HTML 字符串转成 satori 可消费的虚拟节点树 → satori 输出 SVG → resvg 按宽度 1200 栅格化为 PNG。
png 的拷贝动作(new Uint8Array(...) + set)不是冗余:resvg 返回的是 Uint8Array<ArrayBufferLike>,直接作为 Response 的 body 不满足 web BodyInit 的类型要求,拷贝成 ArrayBuffer 支撑的视图后才能在两处端点里直接 new Response(png, …)。这是任务 2.1 之外的实现细节,但正是这类细节决定了“泛化”是否真的可复用。
职位卡退化成一行薄包装:
export async function renderCardPng(job: Job, opts: { fonts: OgFont[]; logo: string | null }) {
return renderMarkupPng(buildCard(job, { logo: opts.logo }), opts.fonts);
}
设计文档对这一步的表述是“keeps one render/resvg code path”——全站只剩一条渲染路径,意味着字体加载、SVG 栅格化、PNG 输出的任何改进都只改一处。
企业 OG 卡片:内容、降级与端点契约
卡片内容构成
company.ts 的 buildCompanyCard(company, { logo, openJobs }) 按从上到下的顺序组织内容:
- 头部:
logoBox(..., 140)主视觉 logo + 56px 企业名,两者水平排列(L15、L46-L49); - 中部:44px 的“N open jobs”主数字,可选 tagline(28px),可选 chips 行;
- 底部:
brandFooter()。
开放职位数的文案用一个小函数保证语法正确:
const jobsFmt = new Intl.NumberFormat('en');
function openJobsLabel(n: number): string {
return `${jobsFmt.format(n)} open ${n === 1 ? 'job' : 'jobs'}`;
}
这同时满足了规格里两条容易漏掉的要求:单复数正确(1 open job 而非 1 open jobs)和千位分组(1,234 open jobs)。
chips 的构造只取第一行业与 HQ 国家(L25-L31),且每一项都做了“存在才 push”的处理:
function chips(company: Company): Chip[] {
const out: Chip[] = [];
const industry = company.industries?.[0];
if (industry) out.push({ text: industry });
if (company.hq_country) out.push({ text: countryLabel(company.hq_country) });
return out;
}
countryLabel 来自 facets.ts,用 Intl.DisplayNames(['en'], { type: 'region' }) 把 US 解析成可读国名,解析失败则回退大写代码。设计文档明确记录了这里的一个决策:不用 emoji 国旗,因为当前 satori 字体集里没有 emoji 字体,画出来只会是方框。同样地,tagline 缺失时整行不渲染,chip 行缺失时整行不渲染——规格要求“不得出现空的或占位的标签,也不得出现字面量 null/undefined”。
端点契约与并发取数
企业端点在 companies/[slug]/og.png/+server.ts 中实现,契约与职位端点对齐:
| 契约项 | 行为 |
|---|---|
| 成功响应 | 200,Content-Type: image/png,body 为合法 PNG |
| 未知 slug | 404,不返回图像 |
| 缓存 | public, max-age=3600, stale-while-revalidate=86400 |
实现上有一个值得一提的并发优化。职位计数只需要 slug,不依赖企业实体,所以端点先发起搜索、再取实体,两者重叠执行:
const openJobsFacets = new URLSearchParams({ company_slug: params.slug });
const openJobsPromise = api.searchJobs(openJobsFacets, 1, 0);
随后 getCompany(params.slug, 1, 0);若它抛出 404,则先 openJobsPromise.catch(() => {}) 吞掉在途请求的拒绝,再 error(404, 'Company not found')——注释明确解释了原因:否则那个没人等待的 Promise 会变成 unhandled rejection。这是一条容易被忽略的正确性细节。
拿到实体后,计数、字体、logo 三件事并行:
const [openJobsSlice, fonts, logo] = await Promise.all([
openJobsPromise,
loadOgFonts(),
resolveLogo(company.name),
]);
这里刻意复用企业详情页的同一条读取路径(searchJobs({ company_slug }) 的 total),从而保证卡片上的数字与页面上的数字一致——规格里“count matches the company's current open-jobs total from the same search read path”正是这条要求。对比之下,详情页 loader(+page.server.ts)也是先起搜索再取实体,注释里记录了同样的理由:成本是较慢的那个,而不是两者之和。
Logo 解析失败绝不拖垮渲染
logo.ts 的 resolveLogo 服务于同一个目标:satori 不能自己抓远程图片,所以服务端先取字节、再转成 data-URI 交给 satori 内嵌。
它对任何失败都返回 null:URL 为空、响应非 2xx、字节长度为 0、抛异常(含 2.5 秒超时)。返回 null 的语义就是“请用字母瓦片”。因此规格中“logo 解析失败 SHALL NOT fail the image render”是被结构性地保证的——不存在让 logo 异常冒泡到端点的路径。
一点实现与早期规格的差异值得记录:企业卡规格文本写的是“resolved from the logo.dev name endpoint”,而当前代码走的是自有代理 https://logo.freehire.me(web/src/lib/logo.ts),代理背后是第三方 favicon 服务,命中失败时返回干净的 404,由各消费方自行降级。也就是说,规格里的“logo.dev”应理解为“按公司名解析 logo 的外部服务”这一类表述,具体主机在实现中换成了可自控的代理。阅读规格时以代码为准会更准确。
静态品牌卡:把“站点门面”编译成一个 PNG
卡片结构
brand.ts 是纯同步函数,输入一组 BrandStat[],输出 HTML 字符串,布局为三段式(justify-content: space-between):
- 顶部:52px 品牌标记 + 44px
freehire字标,右侧freehire.me; - 中间:最大宽度 940px 的 64px 大标题;
- 底部:横向 stat-strip,每个统计项大数值(52px)压在灰色标签(24px)之上。
这里有一个必须如实说明的细节:当前实现的标题常量与早期提案文案并不相同。提案和已归档规格里写的是 “Open source job aggregator that covers all ATS”,而 brand.ts 中的 HEADLINE 是 The open-source search engine for every job。同理,统计数据也从规格描述的三项(open jobs / companies / ATS platforms)扩展成了四项(含 Telegram channels)。这属于规格归档后实现继续演进造成的文本漂移,改动文案或统计项时以生成脚本里的常量为唯一事实来源更稳妥。
生成脚本:复用真实渲染核心,不新增依赖
gen-og.mjs 的设计目标是“用生产同一套渲染核心生成静态资源”,因此它没有引入任何新依赖,而是通过 Vite 的 SSR loader 直接加载 TypeScript 源码:
const vite = await createOgVite();
const { renderMarkupPng } = await vite.ssrLoadModule('/src/lib/server/og/render.ts');
const { buildBrandCard } = await vite.ssrLoadModule('/src/lib/server/og/brand.ts');
const fonts = await loadFonts();
const png = Buffer.from(await renderMarkupPng(buildBrandCard({ stats: STATS }), fonts));
这样做的直接收益是:源码里可以继续使用项目惯用的无扩展名导入和 #lib 别名,不需要为了一个脚本改 tsconfig,也不需要额外搭建测试框架。
统计数字是脚本顶部的常量,当前取值为(L24-L29):
const STATS = [
{ value: '3.3M+', label: 'unique jobs' },
{ value: '470K+', label: 'companies' },
{ value: '300+', label: 'sources' },
{ value: '90+', label: 'Telegram channels' },
];
注释交代了取数口径与时间:数据取自 /api/v1/stats/catalog 并于 2026-10-19 向下取整;职位数用的是去重后的 unique_open_jobs(即 /jobs 展示的口径),而不是原始 open_jobs——后者会把同一条招聘按看板重复计数,读数比用户实际能浏览到的高出约 40%。这段注释解释了为什么首页的 fallback 值(HomeView.svelte 中的 3.3M+ / 290K+ / 220+)与品牌图常量不完全一致:首页是全站统计的另一组展示项,而品牌图只取四项并各自向下取整。
STATS 里的 sources 标签也经过了刻意的语义修正。首页代码注释记录了这次改名:该计数覆盖整个适配器注册表,而不只是 ATS 平台——227 个适配器中有 104 个聚合器和 30 个单公司招聘源,所以原来的“ATS platforms”标签在描述它并不描述的东西。品牌卡沿用“sources”这一更准确的表述。
共享 bootstrap 与 PNG 有效性断言
两个脚本共用 og-render.mjs,它把三件事收敛到一处:
createOgVite():以web/为 root、configFile: false创建 Vite 服务,并把原生模块@resvg/resvg-js标记为 external(否则 SSR 加载会尝试打包原生二进制);loadFonts():读取src/lib/server/og/fonts/下的 Inter Regular/SemiBold/Bold 三个字重,组装成 satori 需要的{ name, data, weight, style };isValidPng():校验 PNG 签名(89 50 4E 47 0D 0A 1A 0A)且长度大于 2000 字节。
isValidPng 的第二条判断(> 2000 字节)值得注意:仅校验签名无法排除“渲染出一张纯白小图”的情况,而一张 1200×630 且带文字与图形的 PNG 不可能只有两千字节。生成脚本在写文件前就用它做断言,失败时 process.exit(1)。
生成脚本的失败语义也很明确:main().catch 打印错误并以非零码退出,finally 里关闭 Vite,因此无论成功失败都不会留下悬挂的服务进程。
脚本通过 npm 脚本暴露(web/package.json):
cd web
pnpm og:gen # 即 node scripts/gen-og.mjs,重新生成并写入 web/static/og.png
pnpm og:smoke # 即 node scripts/og-smoke.mjs,渲染全部 fixture 并断言合法 PNG
仓库中已提交的 web/static/og.png 约 40 KB——设计文档对此的评估是“小体积、可源码再生,作为静态资源可接受且标准”。
全站默认 og:image:一行派生值解决 90% 的页面
真正的“全覆盖”落地在 Seo.svelte。image 保持可选,缺省时回退到站点自身的品牌图:
import { page } from '$app/state';
const previewImage = $derived(image ?? `${page.url.origin}/og.png`);
page 来自 $app/state,在 SSR 阶段即可用,因此爬虫和链接预览机器人拿到的是初始 HTML 里的绝对 URL,而不是客户端水合后才补齐的标签。这一点是必须的:og:image 按规范要求绝对地址,且大多数抓取器不执行 JavaScript。
随后五个标签无条件输出(L50-L60):
<meta property="og:image" content={previewImage} />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content={title} />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content={previewImage} />
因为 og:image 永不为空,twitter:card 可以固定为 summary_large_image——这正是规格里“每页都发出大图卡片”的可验证形式。显式声明宽高还能让部分抓取器在图片下载完成前就按 1.91:1 预留版面,避免首屏跳动。
页面级覆盖只需一个属性。企业详情页:
<Seo title={pageTitle} {description} {canonical} {robots}
image={`${origin}/companies/${data.slug}/og.png`} />
职位详情页则以 canonical 为基准拼出预览地址,保证图与页同源(jobs/[slug]/+page.svelte):
const canonical = $derived(`${origin}/jobs/${data.job.public_slug}`);
// The per-job OG preview lives beside the canonical URL; og:image must be absolute.
const ogImage = $derived(`${canonical}/og.png`);
按同样的模式,仓库里已经扩展到更多路由:博客文章、贡献者主页、企业招聘趋势页都各自传入 image;/open 与 /about 则指向 Go 侧提供的 /api/v1/og/open.png、/api/v1/og/about.png(见 internal/api/handler/og.go)。也就是说,og-brand-cards 确立的“默认 + 覆盖”模型成了后续新增卡片路由的统一范式。
验证与日常维护
任务清单第 7 组记录了完整的验证路径,这套路径在仓库中都可以复现:
- 渲染层:
pnpm og:gen与pnpm og:smoke,前者写web/static/og.png,后者把全部 fixture 渲染到/tmp/og-smoke/*.png,逐个断言合法 PNG 并打印字节数; - 端点层:本地 SSR(dev 环境并把
VITE_API_URL指向生产,按 SSR 校验说明)直接fetch/companies/<slug>/og.png与/jobs/<slug>/og.png,保存后目视检查 logo;再 view-source/与/companies/<slug>,确认前者是品牌默认图、后者是企业图; - 工程门禁:
pnpm check与pnpm lint全绿。
冒烟脚本的 fixture 覆盖了企业卡的全部降级分支(og-smoke.mjs):
| fixture | 覆盖场景 |
|---|---|
companyFull |
有 tagline、有行业、有 HQ、128 个职位 |
companyNoChips |
无 tagline、无行业、无 HQ(仅名称 + 数字) |
companyOneJob |
单数文案 1 open job |
companyZeroJobs |
0 open jobs + 有 tagline 但无 chips |
四个 fixture 全部以 logo: null 渲染,因此字母瓦片分支每次都会被执行——脚本注释对此的解释是:satori 无法获取远程图片,所以“头像/logo 未解析成功”也必须能产出合法 PNG,而这条路径正好由 fixture 天然覆盖。
需要注意的是,冒烟脚本断言的是合法 PNG,不是视觉正确。任务 3.1 与 7.1 都明确要求人工查看 /tmp/og-smoke/ 与 web/static/og.png——字体缺失、文字溢出裁切、chip 换行异常这类问题,签名校验是发现不了的。
什么时候必须重新生成品牌图
设计文档把“烘焙进去的数字会与真实目录漂移”列为已知风险,并给出缓解策略:数字带 + 表示量级、只用于通用页;职位卡与企业卡保持实时;目录明显增长时重跑 og:gen 并重新提交。
结合 gen-og.mjs 的注释,一次规范的更新流程是:
- 从
/api/v1/stats/catalog读取当前口径(职位取unique_open_jobs); - 对
STATS各值向下取整——目录会因职位关闭和去重而收缩,向上取整最终会夸大一个 API 无法支撑的数字; - 更新
STATS常量,pnpm og:gen重新生成; - 打开生成的 PNG 目视确认排版未溢出;
- 提交
web/static/og.png与脚本改动。
风险与权衡复盘
| 风险 | 实际处置 |
|---|---|
| 烘焙数字漂移 | 用 + 表示近似、仅限通用页;实时数字交给职位卡/企业卡;增长时重生成 |
| satori 仅支持 flexbox | 所有多子节点容器显式 display:flex;smoke 与 gen 真实渲染以捕获违规 |
| 提交二进制 PNG | 体积小(约 40 KB)、可由源码再生,属常规静态资源做法 |
| 品牌卡出现动态端点 | 已明确排除:品牌图内容固定,静态文件的请求成本为零 |
| emoji 国旗 | 已明确排除:字体集无 emoji,HQ 改用 countryLabel 文本 |
如果要把这套方案迁移到别的项目,最短路径是:先抽出 shared.ts 这类纯函数原语,再把渲染核心泛化成 markup → PNG,最后用“默认值 + 页面覆盖”的方式落 og:image。freehire 的实践表明,这三步做完之后,新增一种卡片(博客、贡献者、招聘趋势)只剩下“写一个 builder + 一个端点 + 一行 image”的成本。
相关文件索引
- 提案与规格:proposal.md、design.md、tasks.md、og-brand-image 规格、company-og-images 规格
- 卡片构造:shared.ts、card.ts、company.ts、brand.ts、blog.ts、contributor.ts
- 渲染与资源:render.ts、fonts.ts、logo.ts、avatar.ts
- 端点:companies/[slug]/og.png、jobs/[slug]/og.png、blog/[slug]/og.png、contributors/[login]/og.png
- 元数据与生成:Seo.svelte、gen-og.mjs、og-render.mjs、og-smoke.mjs、web/static/og.png