静态html生成阶段无法靠js修改document.head，必须在构建时或响应前完成元信息注入，否则seo、预加载、opengraph等关键行为全失效，因为浏览器和爬虫仅读取初始html中的meta标签，js动态操作无效。

静态 HTML 生成阶段无法靠 JS 修改 document.head，必须在构建时或响应前完成元信息注入——否则 SEO、预加载、Open Graph 等关键行为全失效。

为什么不能等页面加载后再改 meta 标签

浏览器解析 HTML 时，<meta> 标签（尤其是 charset、viewport、og:image、description）在首次解析阶段就被读取并生效。JS 动态插入或修改只影响后续渲染逻辑，对爬虫、分享卡片、PWA 安装提示等完全无效。

• og:image 必须在初始 HTML 响应中存在且为绝对路径，否则微信、LinkedIn 等平台抓取为空
• theme-color 和 apple-mobile-web-app-status-bar-style 只在首次加载时被识别，JS 后续设置无效果
• 搜索引擎只索引初始 HTML 中的 <title></title> 和 meta[name="description"]，不执行 JS

sub_filter 替换 meta 内容的实操限制

Nginx 的 sub_filter 能在响应流中替换文本，但它不解析 HTML 结构，所以只能用于简单字面量匹配，且极易出错。

Doc To HTML

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

下载

• 必须显式声明 sub_filter_types text/html，否则默认不处理 text/html 以外类型（即使 MIME 正确）
• 不能跨标签匹配，例如想把 <meta name="description" content="<!-- DYNAMIC -->"> 替换为真实值，但 <!-- DYNAMIC --> 若被换行或空格分隔，sub_filter 就失效
• 若 HTML 中有多个同名 meta（比如两个 name="description"），sub_filter 会全部替换，无法精准定位
• 不支持变量嵌套，如 sub_filter 'API_BASE_URL' $backend_url 在 location 块中无效，必须用 map 提前定义好字符串变量

构建时替换比运行时更可靠

真正可控的方式是在静态生成阶段注入元信息，而非依赖 Nginx 或客户端 JS。

• 用模板引擎（如 Nunjucks、Pug）时，直接传入 page.title、page.description 等上下文变量，生成时写死进 HTML
• CI/CD 流程中用 sed 或 jq + html-minifier 批量替换占位符，例如 <!-- TITLE --> → <title>${TITLE}</title>
• 若用 webpack/vite 构建，可通过 html-webpack-plugin 的 templateParameters 注入环境变量，避免硬编码
• 注意：所有占位符需加唯一前缀（如 %%META_DESCRIPTION%%），防止误替换正文中的相似字符串

多环境元信息必须靠构建参数驱动

开发、预发、生产环境的 og:url、canonical、robots 等必须不同，但不能靠人工改 HTML 文件。

• 推荐做法：构建命令中传入 --env=prod，由构建脚本读取 .env.prod 并注入到 HTML 模板
• 禁止用 JS 判断 window.location.host 动态设 og:url —— 分享时抓取的是原始 HTML，不是 JS 渲染后结果
• CDN 缓存下，Nginx sub_filter 对同一 URL 返回相同内容，无法按 Host 区分环境；而构建时生成不同 HTML 文件可天然隔离

真正难的不是“怎么换”，而是“在哪换、何时换、换完是否被正确消费”。元信息一旦漏掉或格式错，就失去语义价值，且很难被发现——直到分享链接不显示图、搜索结果标题不对、PWA 安装失败才暴露问题。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！