HTML代码中Twitter Card元数据的配置实战-html教程-PHP中文网

twitter card类型必须严格匹配官方四种且全小写，图片需https完整url、1200×600尺寸、1.91:1~1:1宽高比；title≤70、description≤200 unicode字符；meta须服务端直出，不可js注入；验证须用card validator并关注缓存。

html代码中twitter card元数据的配置实战

Twitter Card类型选错会导致预览不显示

Twitter 不会自动 fallback 到 summary，如果 twitter:card 值拼写错误（比如写成 "summary_large_image" 少了下划线），或用了 Twitter 已弃用的类型（如 "photo"），卡片就完全不渲染。官方只支持四种： summary、summary_large_image、app、player，其中前两种最常用。

实际配置时优先用 summary_large_image —— 它对链接预览友好，且能触发更大图展示；但前提是图片必须满足 1200×600 最小尺寸，且不能是本地路径（file://）或相对路径（/img/cover.jpg），必须是完整 HTTPS URL。

twitter:card 的值必须全小写、无空格、严格匹配
图片宽高比必须在 1.91:1 到 1:1 之间，否则 Twitter 会静默忽略
测试时别依赖“发推即见”，要用 Twitter Card Validator，它会返回具体拒绝原因（比如 "ERROR: Invalid image URL"）

title 和 description 的截断逻辑很隐蔽

Twitter 对 twitter:title 和 twitter:description 有硬性长度限制：标题最多 70 字符，描述最多 200 字符——超长部分会被截断，且不加省略号。更麻烦的是，它按 Unicode 码点计数，中文、emoji、全角标点都算 1 个字符，但某些组合 emoji（如 ?‍?）可能占 2–4 个码点，容易误判。

常见翻车场景是 CMS 自动生成的 description 带 HTML 标签（如 <p>Hello</p>）或空格缩进，这些字符全计入限额。建议后端输出前做 trim + 截断，而不是靠前端 JS 拼接。

用 substring(0, 70) 或正则 ^.{0,70} 截断 title，别用 word-break
description 中避免换行符 \n 和不间断空格，它们都算字符
如果页面语言是中文，70 个汉字 ≈ 70 字符，但带 emoji 时务必用 Array.from(str).length 精确计算

图片 URL 必须可被 Twitter Bot 直接抓取

Twitter 的爬虫（Twitterbot/1.0）不会执行 JS，不走浏览器缓存，也不带 Cookie。所以哪怕你在 <img> 标签里能正常显示的图，只要它依赖登录态、Referer 限制、或 CDN 配置了 no-cache + 动态 token，Card 就会显示空白或报 "ERROR: Fetching the image failed"。

Doc To HTML

使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。

下载

最稳妥的做法是把卡片图放在静态资源目录，配好 CORS（Access-Control-Allow-Origin: *），并确保响应头包含 Content-Type: image/jpeg（不是 text/html 或空）。如果用云存储，检查 bucket 权限是否设为 public-read。

不要用 srcset 或 picture 元素里的图片地址作为 twitter:image
避免使用参数化 URL（如 cover.jpg?v=2024），Twitter 可能缓存旧版本
验证时留意 validator 页面右上角的 “Crawled as” 时间戳，确认它读到的是最新响应

多语言页面的 card 元数据不能靠 JS 注入

Twitterbot 不执行 JavaScript，所有 twitter:* meta 标签必须在 HTML 初始响应中存在，不能靠 document.createElement 或 React useEffect 动态插入。这对 i18n 场景尤其致命——比如用户切换语言后，JS 改写了 twitter:title，但 Twitter 抓取的仍是服务端吐出的默认语言版本。

解决方案只有两个：服务端根据 Accept-Language 渲染不同 meta，或为每种语言生成独立 URL（如 /en/article / /zh/article），并在各自页面硬编码对应语言的卡片信息。后者更可靠，因为 twitter:locale 并不控制 title/description 内容，只影响日期格式等次要字段。