边缘计算下动态HTML内容组装与渲染实践

边缘节点上能否直接调用 document.getElementById？答案非常明确：不行。根本原因在于——边缘计算平台本质上并非浏览器环境。

像 Cloudflare Workers、Fastly Compute@Edge 这类边缘运行时，完全不具备 DOM 环境。document 对象根本不存在，一旦调用就会触发 ReferenceError: document is not defined。这既不是配置项问题，也不是某个库的 bug，而是架构层面的根本性错位——边缘节点不负责解析 HTML、不挂载元素，更不会触发任何生命周期事件。简单来说，它就是一个纯计算环境，与浏览器分属两个完全不同的世界。

那么正确做法是什么？服务端字符串组装。采用模板字符串、Mustache 这类轻量级模板引擎，在请求到达时直接拼接出完整的 HTML 片段。所有变量必须来源于请求上下文——request.headers.get('User-Agent')、env.GEO_REGION 这些才是合法来源。客户端 JS 获取的数据，不能直接拿到边缘使用；想在边缘维护复杂状态，同样行不通。

这里有几条硬性规则：

• 禁止在边缘函数中编写 document.createElement、innerHTML、querySelector
• 允许使用 String.prototype.replace、new URL()、JSON.stringify() 这类纯 JS 字符串或对象操作方法
• 如果需要结构化生成内容，优先采用 HTMLTemplateElement 的服务端模拟逻辑——说白了就是手动构造字符串，别试图创建真实的 DOM 实例

边缘节点上为什么不能用 document.getElementById？

因为边缘运行时（包括 Cloudflare Workers、Fastly Compute@Edge 等）不具备 DOM 环境，document 对象根本不存在。最常见的错误就是直接把前端逻辑搬到边缘——一执行就会报 ReferenceError: document is not defined。这绝不是配置问题，而是架构层面的错配。边缘不是浏览器，它不解析 HTML、不挂载元素、不触发生命周期。

真正可行的替代方案是服务端字符串组装。利用模板字符串、Mustache 或轻量级模板引擎，在请求到达时拼出完整的 HTML 片段。所有变量必须来自请求上下文（例如 request.headers.get('User-Agent')、env.GEO_REGION），而不是通过客户端 JS 去获取。

• 禁止在边缘函数中编写 document.createElement、innerHTML、querySelector
• 允许使用 String.prototype.replace、new URL()、JSON.stringify() 这类纯 JS 字符串/对象操作
• 若需结构化生成内容，优先采用 HTMLTemplateElement 的服务端模拟逻辑（即手动构造字符串，非真实 DOM 实例）

v-html 在边缘渲染中完全不适用

v-html 是 Vue 的运行时指令，依赖浏览器 DOM 和 Vue 的响应式系统，只能在客户端执行。将其放到边缘节点会直接失败——既没有 Vue 实例，也没有 el.innerHTML 可供赋值。

真正的替代方案是：在边缘完成 HTML 字符串拼接，将最终结果作为 HTTP 响应体返回；客户端仅做最小化接管——比如补充动态评论、埋点就够了，而不是依赖 v-html 进行二次渲染。

这里有几个要点：

• 边缘层输出的 HTML 必须是“可直接流式返回”的完整片段，包含 和基础样式
• 个性化区块（如用户昵称、本地天气）要提前注入，不能留空位等客户端来填充
• 如果必须保留部分动态能力，使用 ESI（Edge Side Include）语法或自定义占位符（如 ），再由边缘脚本替换

缓存键设计决定个性化能否生效

边缘缓存默认按 URL 缓存，但新闻、用户仪表盘这类页面，同一个 URL 下内容可能千差万别。如果不做区分，北京用户看到上海用户的首页，或者未登录用户看到已登录态的 HTML，这就是典型的缓存污染。

关键是在缓存键中显式包含影响内容的维度。举个例子：url + geo + device + auth_status。在 Cloudflare Workers 中可以这样编写：cacheKey = new URL(request.url).toString() + request.cf.city + request.headers.get('User-Agent').includes('Mobile')。

• 静态区块（如页眉、页脚）可以设置长缓存：Cache-Control: public, max-age=3600
• 个性化区块（如推荐栏、实时评论数）必须禁用缓存或设置极短 TTL：max-age=10
• 避免用 Cookie 生成缓存键——多数 CDN 默认不将其纳入缓存哈希，除非显式开启 Include-Cache-Key-Headers

流式响应比整页组装更能抗延迟

等待所有数据（API 调用 + 模板渲染）全部完成后再返回 HTML，首字节时间（TTFB）会被放大。尤其当中心 API 偶尔响应慢时，用户白屏时间会直线上升，体验极差。

更优的做法是流式组装：先返回 HTML 开头（doctype、head、骨架），然后边 fetch 边写入 body 内容。Cloudflare Workers 支持 ReadableStream + TransformStream，Fastly 也支持 streaming 模式。

• 静态框架部分（导航栏、加载占位符）应该硬编码在边缘函数开头，立即输出
• 动态区块用占位符包裹（例如

  {NEWS_CONTENT}

  ），fetch 完成后 replace 即可
• 注意：流式响应无法设置 Content-Length，必须使用 Transfer-Encoding: chunked，客户端需要兼容

边缘渲染真正难的不是拼字符串，而是厘清哪些该在边缘做、哪些必须回源、哪些干脆不该动。比如“已读文章列表”这种有状态的数据，边缘只负责传递 token 校验，真实读取还是得走中心服务。这个边界一旦混淆，迟早会掉进缓存不一致或安全漏洞的坑里。