freehire Open Graph 卡片体系解析:从静态品牌图到 Sky 三层 og:image 渲染管线

原创2026-10-24 12:17:502,001 阅读
文章标签:后端前端搜索引擎网页爬虫数据工程AI 应用可观测性

freehire Open Graph 卡片体系解析:从静态品牌图到 Sky 三层 og:image 渲染管线

freehire 作为面向求职者的开源职位搜索引擎,分享链接的视觉呈现直接影响点击率。本文以 openspec/changes/archive/2026-07-04-og-brand-cards/design.md 这份设计文档为主线,拆解 freehire 如何用「静态品牌 PNG + 按需渲染的职位卡 + 按需渲染的公司卡」三层结构,让每一个页面都拥有品牌化的链接预览。读完后你将掌握:satori → resvg 的卡片渲染链路、把品牌原语抽取为 og/shared.ts 的工程动机、公司卡端点的并发与降级策略,以及如何用仓库自带的脚本生成和校验这些图片。

背景:一条只为职位页服务的 OG 管线

设计文档的 Context 一节交代了改造前的真实状态,可以归纳为三个事实:

  • 站点已经存在一条按职位渲染的 OG 管线:src/lib/server/og/{card,render,fonts,logo}.ts 通过 satori → resvg → PNG 生成卡片,由 GET /jobs/:slug/og.png 对外提供。
  • Seo.svelte 只在页面传入 image 属性时才输出 og:image,而当时只有职位详情页传了这个属性。
  • 其余所有页面——首页、公司页、板块页、营销页——分享出去都是没有配图的裸链接。
  • 此外,可复用的品牌原语(标记、转义、字母组合、logo/页脚标记)当时全部内联在 card.ts 里,一旦要新增卡片类型,就只能复制粘贴。

正是这四点,构成了这次改造的全部动因:不是「加个图片」,而是把一套散落的、单点的渲染逻辑,收敛成一套有层级、可复用、不漂移的品牌视觉体系。

目标与非目标:先把边界钉死

设计文档明确划定了 Goals 与 Non-Goals,这种「先否定一部分需求」的写法值得借鉴。

Goals:

  • 每个页面默认都有品牌化链接预览;
  • 公司页拥有以 logo 为主视觉、符合品牌调性的预览图;
  • 职位卡、公司卡、品牌卡共享同一套品牌语汇,且不可能发生漂移。

Non-Goals(同样重要):

非目标 理由
不做动态首页 OG 端点 品牌卡内容基本固定,提交一张静态 PNG 即可,零运行时开销,数字变化时按需重新生成
不用 emoji 国旗 当前 satori 环境没有加载 emoji 字体,公司总部只能用 countryLabel 输出文本国家名
不改动 Go 后端 / 数据库 / API 这是纯粹的前端展示层改造

「不做动态端点」这条尤其关键:首页的品牌卡上印的是「3.3M+ unique jobs」这类静态数字,如果做成动态端点,每次爬虫抓取都要走一次数据查询,而抓取到的内容又几乎不会变——投入产出完全不成立。

三层结构:后一层覆盖前一层

设计文档的核心决策是三层图片,逐层覆盖:

  1. 静态品牌 PNG(站点默认)——web/static/og.png,对外路径 /og.png;
  2. 职位卡——/jobs/:slug/og.png,改造前已存在;
  3. 公司卡——/companies/:slug/og.png,本次新增。

层级选择机制简单到极致:页面向 <Seo> 传了哪个 image,就用哪个图;不传就是品牌 PNG 默认图。文档还专门记录了一个被否决的替代方案——「做一个返回实时数字的动态 /og.png 端点」——否决理由写得很直白:品牌卡本质固定,提交态 PNG 更简单,且请求时完全免费。

这套「覆盖式选择」在代码里落实得非常轻量,见 Seo.svelte:

const previewImage = $derived(image ?? `${page.url.origin}/og.png`);

image 保持可选,缺省时用 page.url.origin 拼出绝对地址(OG 协议要求绝对 URL),并且这里从 $app/state 导入 page,因此 SSR 阶段即可正确求值,爬虫拿到的初始 HTML 里就带着完整标签。随后 og:image、og:image:type/width/height/alt、twitter:image、twitter:card=summary_large_image 无条件输出,这意味着任何页面都不可能再出现「无预览图」的退化状态。

职位页与公司页则各自覆盖默认值,例如 公司详情页 传入 image={origin/companies/{origin}/companies/{data.slug}/og.png},职位详情页 同理。

共享品牌原语:og/shared.ts 的抽取

设计文档的第二个关键决策是把散落在 card.ts 中的品牌积木抽到 og/shared.ts,并明确列出提取清单:OG_WIDTH/OG_HEIGHT、esc、monogram、MARK_DATA_URI、logoBox(logo, name, size)(按尺寸参数化、圆角与字号等比、字母组合兜底)、Chip/chipMarkup、brandFooter();card/company/brand 三方全部改为 import。

文档同时记录了被否决的方案:在每个卡片里各复制一份 base64 标记和 chip 样式。否决理由一针见血——「样式漂移,以及 3 份 base64 大块」。

常量与品牌标记

shared.ts 定义了统一的画布尺寸与标记:

export const OG_WIDTH = 1200;
export const OG_HEIGHT = 630;

const MARK_SVG =
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">' +
  '<path fill-rule="evenodd" clip-rule="evenodd" d="M256 56C366.457 56 ... 256 166L346 256L256 346L166 256Z" fill="#0a0a0a"/>' +
  '</svg>';
export const MARK_DATA_URI = `data:image/svg+xml;base64,${Buffer.from(MARK_SVG).toString('base64')}`;

这里出现了一个非常实际的约束:satori 无法抓取远程图片。所以 freehire 的圆形标记(带菱形镂空)被内联为 base64 data-URI,颜色取 #0a0a0a,与旁边的 wordmark 保持一致。这个「不能远程取图」的限制在后面还会反复出现。

转义:不可省略的一行

export function esc(s: string): string {
  return s
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;');
}

卡片 HTML 是由字符串拼接出来的,职位标题、公司名、标签全部来自抓取数据——任何一条都可能是不可信输入。所有插值必须过 esc,否则一张图就可能变成 HTML 注入面。

字母组合兜底:monogram 与 logoBox

monogram 取名字的前两个有效词的首字母(单词只有一个时取前两个字符),空名字回退 '?'。logoBox 在此之上做了三件事:

export function logoBox(
  logo: string | null,
  name: string,
  size: number,
  shape: 'tile' | 'circle' = 'tile',
): string {
  const radius = shape === 'circle' ? '50%' : `${Math.round(size / 5)}px`;
  if (logo) {
    const fit = shape === 'circle' ? 'cover' : 'contain';
    return `<img src="${esc(logo)}" style="width:${size}px;height:${size}px;border-radius:${radius};object-fit:${fit}" />`;
  }
  const font = Math.round(size * 0.42);
  return (
    `<div style="display:flex;align-items:center;justify-content:center;width:${size}px;height:${size}px;` +
    `border-radius:${radius};background:#f4f4f4;color:#525252;font-size:${font}px;font-weight:700">` +
    `${esc(monogram(name))}</div>`
  );
}

三个设计细节值得单独指出:

  1. 尺寸参数化后等比缩放:圆角为 size/5,字母组合字号为 size*0.42,因此 72px 的原始职位卡尺寸下恰好还原成「圆角 14、字号 30」,既能给职位卡用 96px,也能给公司卡用 140px,而视觉比例不变。
  2. shape 区分实体与人:注释里说得很清楚——圆角 tile 代表一个组织/实体的标识,circle 代表一个人;把人物裁成方块会让人误读成公司 logo。这个参数是文档设计之外的落地扩展,服务于后加的贡献者卡片。
  3. object-fit 的分叉:人物头像用 cover 裁切填满圆形;实体 logo 用 contain 完整放入方块,因为「边缘被裁掉的 logo 就是一个坏掉的 logo」。
  4. 必须用 style 而非 HTML 属性:注释明确指出 satori 从 style 读取图片尺寸,width/height 属性无效——这是踩过坑才会写下的注释。

chip 与页脚:所有卡片共同的收尾

chipMarkup 有两种形态:普通 chip 是灰底圆角胶囊(background:#f4f4f4,border-radius:999px),muted 形态则是无底色的浅灰文字,专门承载 +N 这类溢出指示。brandFooter() 则统一了「左侧标记 + wordmark / 右侧域名 freehire.me」的底栏,三个卡片构建器都以它收尾,这就是「不可能漂移」的物理保障。

渲染核心:把 render.ts 泛化为 renderMarkupPng

改造前,render.ts 只会渲染 Job。设计文档的解法是下沉一层:新增 renderMarkupPng(markup: string, fonts),而 renderCardPng(job, …) 退化为一个「拼 HTML + 委托」的薄包装。文档对这一决策的表述是「保持单一 render/resvg 代码路径」。

落地实现见 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();
  // resvg returns a Node Buffer (Uint8Array<ArrayBufferLike>); copy into a plain
  // ArrayBuffer-backed view so it satisfies the web BodyInit type at the endpoint.
  const out = new Uint8Array(png.byteLength);
  out.set(png);
  return out;
}

export async function renderCardPng(
  job: Job,
  opts: { fonts: OgFont[]; logo: string | null },
): Promise<Uint8Array<ArrayBuffer>> {
  return renderMarkupPng(buildCard(job, { logo: opts.logo }), opts.fonts);
}

这个函数里有两个容易被忽略但很关键的工程点:

  • 函数刻意不引用任何 SvelteKit 运行时。文件头注释说明它不 import $app/*,因此既能跑在 SSR 服务端(端点负责注入字体与 logo),也能跑在纯 Node 冒烟脚本里。字体加载、logo 抓取、卡片构建各自独立成模块,render.ts 只做「输入 → 输出」的纯变换。
  • 返回值需要拷贝一次。resvg 返回的是 Node Buffer(Uint8Array<ArrayBufferLike>),在 new Response(png, …) 时无法满足 Web 的 BodyInit 类型;代码显式复制到一块新的 ArrayBuffer 视图,从而让类型与运行时都成立。

satori 的硬约束

设计文档在 Risks 里专门写了这条,且 shared.ts、brand.ts、company.ts 的文件头注释都重复了一遍:

satori 只支持 flexbox 布局(不支持 CSS grid),且任何含多个子元素的元素都必须声明 display:flex。

上面的 logoBox 里那个 display:flex 不是随手写的样式,而是渲染能否成功的必要条件。文档还提到,现有 card.ts 本来就遵守这个约束,company.ts/brand.ts 沿用,并且依靠 og-smoke/gen-og 真实渲染来捕获违规——因为这类错误在类型检查阶段完全发现不了。

公司卡端点:并发、缓存与优雅降级

公司卡端点的实现是整篇文章信息密度最高的一处,见 companies/[slug]/og.png/+server.ts。

读取路径与详情页一致。 设计文档要求「通过 getCompany(slug, 1, 0) 取实体,通过 searchJobs({company_slug: slug}, 1, 0).total 取计数——和详情页用同一条读取路径」,目的是让图上的数字与页面上的数字永远一致。实现里还做了一个性能优化:

// The open-jobs count needs only the slug, so start it now — it runs concurrently
// with the entity fetch instead of behind it (mirrors the company-detail loader).
const openJobsFacets = new URLSearchParams({ company_slug: params.slug });
const openJobsPromise = api.searchJobs(openJobsFacets, 1, 0);

计数查询只需要 slug,所以它在实体查询之前就发出,两者并行;随后 Promise.all([openJobsPromise, loadOgFonts(), resolveLogo(company.name)]) 把计数、字体、logo 三件事一起等。

404 的边界处理。 如果公司不存在,那个在途的搜索 promise 会变成未处理的 rejection。代码显式把它「标记为已处理」再抛 404:

} catch (e) {
  openJobsPromise.catch(() => {});
  if (e instanceof ApiError && e.status === 404) error(404, 'Company not found');
  throw e;
}

降级永不阻断响应。 resolveLogo 在 logo.ts 中实现:服务端请求站内 logo 代理,带 2.5 秒超时;非 2xx、空字节或任何异常一律返回 null,由 logoBox 回退到字母组合。注释写得很明确:「缺失 logo 绝不能导致图片渲染失败」。

缓存头与职位端点保持一致(文档原文:public, max-age=3600, stale-while-revalidate=86400)。公司信息变化缓慢、爬虫重取频率低,一小时新鲜期加一天过期后后台续取是合理取舍。

卡片内容与稀疏数据

company.ts 负责把实体变成 HTML:

  • 主视觉 logo:LOGO_SIZE = 140,与 56px 粗体公司名并排(gap: 28px);
  • 活体职位数:openJobsLabel 用 Intl.NumberFormat('en') 做千位分组,并处理单复数——1 open job / 128 open jobs;
  • tagline:company.tagline?.trim(),空白即整段省略;
  • chips:固定顺序取第一个 industry,再取 countryLabel(company.hq_country) 输出的国家文本名(对应 Non-Goal 中「不用 emoji 国旗」)。

所有可选字段都遵循同一条规则——缺失就整段不渲染,绝不出现空 chip 或字面量 null。这一点在 specs/company-og-images/spec.md 中被写成了可验证场景。

品牌卡:把「静态资源」当作一项工程来生成

品牌卡不是运行时产物,而是一张提交进仓库的 PNG。这让它成为本次改造中最容易被误解的部分:既然是静态图,为什么还要写生成器?

答案在 gen-og.mjs 的文件头:品牌卡内容基本固定(标题 + 内置目录数字),因此作为提交态资源优于按需端点——零运行时开销,且它就是所有无专属预览页面的默认 og:image。脚本走真实的 satori 渲染核心(复用 ./og-render.mjs 的共享引导),断言产物是合法 PNG,然后写出。数字增长到一定程度时,重跑并重新提交即可。

脚本中的统计常量值得完整保留,因为它们体现了数据口径的选择:

// Rounded DOWN from /api/v1/stats/catalog on 2026-10-19. The jobs figure is the
// de-duplicated `unique_open_jobs` — what /jobs shows — not the raw `open_jobs`, which
// counts a posting once per board and reads ~40% higher than anything a visitor can
// browse.
const STATS = [
  { value: '3.3M+', label: 'unique jobs' },
  { value: '470K+', label: 'companies' },
  { value: '300+', label: 'sources' },
  { value: '90+', label: 'Telegram channels' },
];

职位数取的是去重后的 unique_open_jobs(即 /jobs 页面真正能浏览到的量),而不是原始 open_jobs——后者按板块重复计数,读数比用户实际可见量高出约 40%。这是一个典型的「宣传数字必须与产品实际体验对齐」的取舍。

对应的 brand.ts 是一个纯同步构建器,导出 buildBrandCard({ stats }),内部用 statMarkup 渲染「大号数值 + 浅灰标签」的双行结构,标题常量 HEADLINE 为 The open-source search engine for every job,整体沿用 1200×630、padding: 64px 72px 的统一版式,并同样以品牌标记 + wordmark 开头、域名收尾。

一个真实的「漂移」注脚:设计文档里举例的统计值是 2.9M+ open jobs / 188K+ companies / 50+ ATS platforms,而仓库中 gen-og.mjs 的实际常量已是 3.3M+/470K+/300+/90+,条目也从 3 个变成 4 个。这恰好印证了设计文档 Risks 的判断——内置数字会随目录增长而失真,只能靠重新生成来跟进。同时 openspec/specs/og-brand-image/spec.md 中记录的标题文案与 brand.ts 中的 HEADLINE 也不一致,以源码为准。

生成与校验命令

web/package.json 暴露了两个脚本:

# 生成品牌卡到 web/static/og.png(失败时以非零码退出)
pnpm og:gen     # 等价于 node scripts/gen-og.mjs

# 冒烟校验:渲染全部 fixture 并检查 PNG 合法性
pnpm og:smoke   # 等价于 node scripts/og-smoke.mjs

og:gen 的输出是一张约 40KB 的平面 PNG(仓库中 web/static/og.png 实际存在,尺寸 40095 字节),提交进仓库后由静态资源层直接对外提供 /og.png。

脚本为什么能直接跑 TypeScript

gen-og.mjs 与 og-smoke.mjs 都是依赖无关的裸 Node 脚本,却能 import 项目里用 #lib/* 别名、省略 .ts 扩展名的源码。桥梁是 og-render.mjs:

export function createOgVite() {
  return createServer({
    configFile: false,
    root: webRoot,
    logLevel: 'error',
    ssr: { external: ['@resvg/resvg-js'] },
  });
}

它用 Vite(项目已有的 devDependency)起一个 SSR 加载器,于是源码保持项目正常写法,不需要改 tsconfig、不需要额外测试框架。文件同时解释了为什么不能复用应用自身的字体加载器:src/lib/server/og/fonts.ts 依赖 $app/server 的 read(),而裸 Vite 脚本没有 SvelteKit 运行时。因此脚本侧另写了 loadFonts(),直接读同一批 Inter 字重(Inter-Regular.ttf 400 / Inter-SemiBold.ttf 600 / Inter-Bold.ttf 700)。

PNG 合法性判定也非常朴素:

export function isValidPng(png) {
  return png.subarray(0, 8).equals(PNG_SIGNATURE) && png.length > 2000;
}

校验文件签名 + 非平凡体积。阈值 2000 字节足以区分「真的渲染出了内容」和「渲染了一张空白/失败图」,成本却近乎为零。

服务端侧则是另一套字体加载:fonts.ts 用 $app/server 的 read() 读取 Vite 导入的 ttf 资源,并在模块级 cache 中记忆化——字体在一个进程生命周期内不会变,文件只需读一次。

冒烟测试:用真实渲染覆盖所有退化分支

仓库没有引入 JS 单元测试框架(设计文档明确说明是刻意不引入),因此 og-smoke.mjs 承担了自动化 RED→GREEN 的职责。它的思路是:构造覆盖各类退化情况的 fixture,跑真实渲染,逐一断言产出合法 PNG,并把图片写到 /tmp/og-smoke/ 供肉眼复核。

职位卡的四个 fixture 分别打中不同分支:

fixture 覆盖的退化场景
full 薪资 + 职级 + 5 个技能(触发技能溢出)
noSalary 缺薪资,薪资 chip 必须整条消失
noLogo logo 为 null,走字母组合兜底
longTitle 超长标题,触发字号收缩 + 三行截断

公司卡另有一组 [entity, openJobs] 配对:companyFull(完整数据)、companyNoChips(无行业无总部)、companyOneJob(单复数边界)、companyZeroJobs(0 个职位)。这四组恰好把 openJobsLabel 的分支和 chip 的省略逻辑全部走到。

值得注意的是,脚本还会渲染贡献者卡片的 6 个 fixture(含超长 GitHub login、仅有 issue 无 PR、maintainer 角色等),且全部以 avatar: null 渲染——因为 satori 取不了远程图片,头像未解析成功时也必须能出图。这说明这套共享原语在落地后已被更多卡片类型复用,og/ 目录下现有的 blog.ts、contributor.ts 都是这一体系的延伸。

职位卡:把「降级」写成了一等公民

虽然职位卡在本次改造前就已存在,但它是三层结构里的第二层,也是理解降级策略的最佳样本,见 card.ts。

标题自适应:titleFontSize 按长度分五档——≤24 字用 64px,≤40 用 52px,≤64 用 42px,≤90 用 34px,更长则 30px;同时 TITLE_LINE_CLAMP = 3 配合 -webkit-line-clamp 做三行截断加省略号。字号不会无限缩小,行数也不会无限增长。

chip 优先级固定:工作方式 → 职级 → 薪资 → 技能,前三个通过共享的展示函数 workArrangement / seniorityLabel / formatSalary(来自 #lib/enrichment)产出——也就是说,图上显示的薪资和页面上显示的薪资走的是同一个格式化器,这正是 specs/job-og-images/spec.md 中「Salary uses the shared formatter」场景的要求。

技能溢出折叠:SKILL_LIMIT = 3,超出部分不再铺开,而是一个 muted 的 +N chip:

const skills = job.skills ?? [];
for (const s of skills.slice(0, SKILL_LIMIT)) out.push({ text: s });
const extra = skills.length - SKILL_LIMIT;
if (extra > 0) out.push({ text: `+${extra}`, muted: true });

所有缺失字段一律「整条不渲染」,绝不出现空 chip 或 null 文本——这条规则从职位卡一路贯彻到公司卡。

风险与取舍:设计文档里最有价值的部分

设计文档的 Risks / Trade-offs 一节,值得逐条对照现状:

  1. 内置数字会与实时目录脱节 → 数字带「+」号、只出现在通用页的品牌卡上;职位卡与公司卡始终实时。目录显著增长时重跑 og:gen 并重新提交。上文的常量变化就是这条风险的实际发生。
  2. satori 只支持 flexbox、多子元素必须 display:flex → 三张卡都遵守,且靠 og-smoke/gen-og 真实渲染兜底。
  3. 提交二进制 PNG → 尺寸很小(≈1200×630 平面图,实际约 40KB),可从源码再生,对静态资源而言是标准做法。

第三条的措辞很有意思:「可接受的,且对静态资源来说是标准做法」。它没有回避「仓库里放二进制」这个常见争议,而是给出了可验证的理由——可再生。

实操清单:从零复现这套体系

如果你要在自己的项目里落地同类方案,可以按下面的顺序推进:

  1. 先抽原语。把尺寸常量、标记 data-URI、esc、字母组合、logo 盒、chip、页脚集中到一个 shared.ts,让所有卡片只 import 不复制。这一步决定了体系会不会在第三次新增卡片时崩掉。
  2. 再泛化渲染核。把「只认某种实体」的渲染函数拆成 renderMarkupPng(markup, fonts) + 若干纯同步的 buildXxxCard()。记住要用样式而非 HTML 属性控制图片尺寸,并处理返回值到 Web BodyInit 的类型转换。
  3. 给页面加默认图。把 image 保持为可选,缺省回退到 ${page.url.origin}/og.png,同时无条件输出 og:image 与 twitter:card=summary_large_image。
  4. 端点对齐读取路径。卡片上的数字必须与页面上一致,因此复用同一个 API 调用;能并行的查询提前发出;404 要把在途 promise 标记为已处理;缓存头给出明确的 max-age 与 stale-while-revalidate。
  5. 降级永不失败。logo 抓取带超时、任何异常返回 null、渲染回退到字母组合;可选字段缺失就整段省略。
  6. 生成器 + 冒烟脚本。静态图用脚本走真实渲染核心生成并断言有效;用 fixture 覆盖每个退化分支,让「改样式改坏了」在 CI 里立刻暴露。

这套分工让 freehire 的 OG 体系同时满足了三个看似冲突的诉求:每个页面都有品牌预览(默认图保证覆盖)、每张图都可用于分享且视觉一致(共享原语保证不漂移)、运行时成本可控(静态图零开销、动态图按需渲染并强缓存)。

登录后查看全文
freehire