社交分享与网站图标
唯一重要的事
og:image 和 og:url 必须是可公开访问主机上的绝对 URL。
爬虫在其自己的服务器上获取它们。它没有页面上下文、没有 cookie、没有 referer,也不知道你的相对路径相对于什么。像 /assets/og.jpg 或 assets/og.jpg 这样的路径解析为空,卡片显示为空白。
<!-- 无效:在所有地方渲染空卡片 -->
<meta property="og:image" content="assets/images/og-image.jpg">
<!-- 有效 -->
<meta property="og:image" content="https://example.com/assets/images/og-image.jpg">
这是预览不工作的最常见原因。在调试其他任何东西之前,先确认 URL 是绝对的并且能在隐私窗口中加载。
推论:预览在 localhost 或 file:// 上无法工作。你在本地做的任何事情都不会产生真正的预览。先部署,再验证。
标签集
<link rel="canonical" href="https://example.com/">
<meta property="og:type" content="website">
<meta property="og:site_name" content="品牌">
<meta property="og:locale" content="zh_CN">
<meta property="og:url" content="https://example.com/">
<meta property="og:title" content="品牌 - 简介">
<meta property="og:description" content="一句话。大约 110 个字符。">
<meta property="og:image" content="https://example.com/og-image.jpg">
<meta property="og:image:type" content="image/jpeg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="图片内容描述">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="品牌 - 简介">
<meta name="twitter:description" content="一句话。大约 110 个字符。">
<meta name="twitter:image" content="https://example.com/og-image.jpg">
<meta name="twitter:image:alt" content="图片内容描述">
三个容易出错的地方:
og: 使用 property=,twitter: 使用 name=。 混淆它们会静默地被忽略,因此标签在源代码中看起来存在但没有任何作用。一些解析器容忍 og: 上的 name=,但不要依赖它。
twitter:card 必须是 summary_large_image。 默认是一个小方形卡片,图片作为缩略图放在文本旁边,这会浪费 1200x630 的图片。
声明 og:image:width 和 og:image:height 能使卡片立即渲染。 没有它们,平台必须下载图片后才能知道宽高比,因此第一个分享链接的人通常会看到纯文本卡片。它们必须与实际文件匹配。测量图片尺寸,不要猜测。
文案长度:标题大约在 60 个字符处截断,描述大约在 110 到 200 个字符之间,具体取决于平台。将重要信息放在开头。
分享图片
1200×630 (1.905:1)。使用 JPEG,除非设计需要透明度(但实际上不需要,因为所有平台都是在白色背景上合成)。保持图片大小在 1 MB 以下;硬性限制是 8 MB(Facebook)和 5 MB(X),但大文件在抓取时容易超时。
按目标宽高比渲染,不要裁剪屏幕截图
截取任意屏幕截图并裁剪到 1.905:1 会丢弃设计师选择的构图。应直接按该宽高比渲染源:
# 1440x756 正好是 1.905:1,因此可以无损缩放到 1200x630
chrome --headless --disable-gpu --hide-scrollbars --virtual-time-budget=8000 \
--window-size=1440,756 --screenshot=og-src.png "file://$PWD/index.html"
短视口陷阱
如果页面有全高的英雄区(100vh / 100svh),直接按 1.905:1 渲染会得到一个比真实桌面屏幕短得多的视口。任何使用 object-fit: cover 的媒体裁剪程度会比实际使用时严重得多,通常能正常分开的元素会互相碰撞——典型情况是标题标志落在主题头部上。
应使用更高的视口渲染,使媒体的裁剪方式与实际使用一致,然后从中切出 1.905:1 的区域:
chrome --headless ... --window-size=1440,1000 --screenshot=og-src.png "file://$PWD/index.html"
ffmpeg -i og-src.png -vf "crop=1440:756:0:0" -q:v 2 og-crop.png # 顶部对齐裁剪
在选择之前,比较顶部对齐裁剪和居中裁剪的效果。顶部对齐通常能保持品牌元素(实用工具栏、导航、品牌标志);居中裁剪通常能保持主题和行动号召。你无法同时拥有两者,因为全高英雄区的高度超过了 1.905:1 所允许的范围。
构图
卡片在信息流中大约呈现为 500 像素宽,并且每个平台的裁剪方式不同(LinkedIn 和 Slack 比 Facebook 更严格)。任何必须在卡片内可见的内容都要放在中央 80% 的区域内,并确保任何文字字号足够大,在缩小到一半时仍可阅读。细小的 UI 细节会消失;大的品牌标志和强烈的图像则不会。
网站图标
字体陷阱
不要在 SVG 网站图标中使用 <text>。
<!-- 损坏:使用观看者本机任何可用的后备字体渲染 -->
<svg ...><text x="50%" y="50%" font-family="Geist">G</text></svg>
SVG 在观看者的机器上渲染,你使用的网页字体并不存在。应将字形提取为路径,使其与字体无关且与分辨率无关。请参阅下面的脚本。
透明度陷阱
深色字形在透明背景上会在深色浏览器 chrome 中消失,浅色字形在浅色背景上也会消失。应将图标绘制在填充的图块上。这也使得标记在标签栏、书签和主屏幕上具有一致的轮廓。
文件集
| 文件 | 尺寸 | 原因 |
|---|---|---|
/favicon.ico | 16, 32, 48 | 即使你声明了其他图标,浏览器也会隐式请求此路径;请将其保持在 web 根目录 |
favicon.svg | 可缩放 | 现代浏览器更偏好此格式,在任何显示器上都能保持清晰 |
apple-touch-icon.png | 180 | iOS 主屏幕 |
icon-192.png | 192 | 清单 |
icon-512.png | 512 | 清单、启动画面 |
icon-maskable-512.png | 512 | Android 自适应遮罩 |
<link rel="icon" href="/favicon.ico" sizes="32x32">
<link rel="icon" href="/assets/icons/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/assets/icons/apple-touch-icon.png">
<link rel="manifest" href="/site.webmanifest">
可遮罩安全区域
Android 会将图标裁剪成任意形状(圆形、圆角方形、泪滴形)。maskable 图标必须将所有重要内容保留在中央 80% 的圆形区域内,这意味着大约 40% 的图块边缘是可丢弃的填充区域。直接重用普通图标会导致其边缘被切掉。
实际操作中:如果标准图标中字形覆盖了图块的 60%,对于可遮罩图标,应将其降至约 40%。同时提供两者,并分别使用 "purpose": "any" 和 "purpose": "maskable" 作为独立条目。切勿将两种目的放在同一个文件上。
Web 清单
{
"name": "品牌",
"short_name": "品牌",
"start_url": "/",
"scope": "/",
"display": "standalone",
"background_color": "#f7f6f4",
"theme_color": "#0a0a0a",
"icons": [
{ "src": "/assets/icons/favicon.svg", "type": "image/svg+xml", "sizes": "any" },
{ "src": "/assets/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
{ "src": "/assets/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
{ "src": "/assets/icons/icon-maskable-512.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
]
}
theme_color 会为移动浏览器 chrome 着色,因此它应该与页面最顶部的内容保持一致,而不是品牌的主色。如果页面打开时顶部是黑色实用工具栏,就使用该黑色。不匹配会被视为渲染错误。请在 <meta name="theme-color"> 中也反映它。
background_color 是首次绘制前图标后面的启动画面,因此应与页面背景色匹配。
生成脚本
需要 pillow 和 fonttools。生成整个图标集以及分享图片。
import os
from PIL import Image, ImageDraw, ImageFont
from fontTools.ttLib import TTFont
from fontTools.pens.svgPathPen import SVGPathPen
from fontTools.pens.boundsPen import BoundsPen
FONT = "brand.ttf" # 真正的品牌字体,使用品牌标志所用的字重
CHAR = "G"
INK = "#0a0a0a" # 图块颜色
PAPER = "#f2f1ed" # 字形颜色
COVER = 0.60 # 字形高度占图块的比例
OUT = "assets/icons"
os.makedirs(OUT, exist_ok=True)
# ── SVG:将字形转换为真实路径,使其不依赖观看者的字体 ──
f = TTFont(FONT)
gs = f.getGlyphSet()
name = f.getBestCmap()[ord(CHAR)]
bp = BoundsPen(gs); gs[name].draw(bp)
x0, y0, x1, y1 = bp.bounds
pen = SVGPathPen(gs); gs[name].draw(pen)
d = pen.getCommands()
VB = 64
s = (VB * COVER) / (y1 - y0)
tx = (VB - (x1 - x0) * s) / 2 - x0 * s
ty = (VB + (y1 - y0) * s) / 2 + y0 * s # y 坐标翻转:字体是 y 向上,SVG 是 y 向下
open(f"{OUT}/favicon.svg", "w").write(
f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {VB} {VB}">'
f'<rect width="{VB}" height="{VB}" fill="{INK}"/>'
f'<path transform="translate({tx:.3f} {ty:.3f}) scale({s:.5f} -{s:.5f})" '
f'd="{d}" fill="{PAPER}"/></svg>')
# ── 栅格化图块 ────────────────────────────────────────────────────────────
def tile(px, cover=COVER):
img = Image.new("RGB", (px, px), INK)
dr = ImageDraw.Draw(img)
fnt = ImageFont.truetype(FONT, px * 2)
bb = dr.textbbox((0, 0), CHAR, font=fnt)
fnt = ImageFont.truetype(FONT, int(px * 2 * (px * cover) / (bb[3] - bb[1])))
bb = dr.textbbox((0, 0), CHAR, font=fnt)
dr.text(((px - (bb[2] - bb[0])) / 2 - bb[0],
(px - (bb[3] - bb[1])) / 2 - bb[1]), CHAR, font=fnt, fill=PAPER)
return img
tile(180).save(f"{OUT}/apple-touch-icon.png", optimize=True)
tile(192).save(f"{OUT}/icon-192.png", optimize=True)
tile(512).save(f"{OUT}/icon-512.png", optimize=True)
tile(512, cover=0.42).save(f"{OUT}/icon-maskable-512.png", optimize=True) # 40% 安全区域
tile(256).save("favicon.ico", sizes=[(16, 16), (32, 32), (48, 48)])
# ── 分享图片:从更高分辨率渲染中裁剪出宽高比,然后缩放到正确尺寸 ──────────────
src = Image.open("og-src.png").convert("RGB") # 例如 1440x1000
src.crop((0, 0, 1440, 756)).resize((1200, 630), Image.LANCZOS).save(
"assets/images/og-image.jpg", quality=88, optimize=True, progressive=True)
没有品牌字体?任何几何无衬线字体都可用于字母组合。将现有的标志 PNG 栅格化到图块上也可以;只需将其居中在相同的 COVER 比例内,并保持可遮罩变体更小即可。
部署前验证
import re, json, os
from PIL import Image
s = open("index.html").read()
tags = dict(re.findall(r'(?:property|name)="((?:og|twitter):[^"]+)"\s+content="([^"]+)"', s))
for t in ("og:url", "og:image", "twitter:image"):
assert tags[t].startswith("http"), f"{t} 不是绝对 URL: {tags[t]}"
w, h = Image.open("assets/images/og-image.jpg").size
assert (str(w), str(h)) == (tags["og:image:width"], tags["og:image:height"]), "声明的尺寸不正确"
assert tags["twitter:card"] == "summary_large_image"
m = json.load(open("site.webmanifest"))
for i in m["icons"]:
assert os.path.isfile(i["src"].lstrip("/")), f"缺少图标 {i['src']}"
print("检查通过")
检查清单:
-
og:image和og:url是绝对 URL,指向真实主机,能在隐私窗口中加载 - 声明的
og:image:width/height与实际文件匹配 -
twitter:card是summary_large_image -
og:标签使用property=,twitter:标签使用name= - 所有占位符域名已替换(搜索一下;通常有四个)
-
favicon.ico位于 web 根目录,而不只是在 assets 文件夹中 - SVG 网站图标包含
<path>,没有<text> - 图标图块是填充的,可以在深色和浅色浏览器 chrome 中正常显示
- 可遮罩图标已填充到中央 80%
-
theme_color与页面顶部边缘颜色匹配
缓存
每个平台都会积极缓存,并在修复后继续提供旧卡片。重新抓取:
- Facebook、Instagram、WhatsApp:https://developers.facebook.com/tools/debug/
- X:https://cards-dev.twitter.com/validator
- LinkedIn:https://www.linkedin.com/post-inspector/
LinkedIn 缓存最严重,除非你运行检查器,否则它基本上会在 7 天内忽略更改。如果某个 URL 已经以损坏的卡片被广泛分享,添加查询字符串(?v=2)会强制进行全新抓取。
网站图标在浏览器中也会被强缓存。请在隐私窗口中测试;正常的重新加载通常会继续提供旧图标。
占位符域名
当真实域名尚不明确时,使用 example.com 的子域名(https://brand.example.com)。RFC 2606 保留了它,因此它明确是一个占位符,永远不会意外指向别人拥有的域名。切勿在已发布的元数据中留下看似合理但无人拥有的域名。
将替换指示直接放在代码块上方的注释中以及项目 README 中,并说明有多少处出现。通常是四处:canonical、og:url、og:image、twitter:image。