静态化改造项目记录：把一个文档站的首屏加载压下来的过程

前段时间接手了一个在线文档站的优化需求：页面能打开，但首屏偏慢，移动端尤其明显，而且部分文章收录不稳定。我们没有急着加服务器配置，而是从“页面是怎么被生成和加载的”入手做了一轮静态化改造。本文记录这次项目的思路、步骤和复盘，供遇到类似情况的朋友参考。 ## 一、先定位：慢在哪里 第一步不是改代码，而是测量。通过浏览器性能面板和几组典型页面的对比，问题逐渐清晰： - 首屏内容依赖脚本请求数据后才渲染，存在明显白屏； - 同步加载的脚本阻塞了解析； - 图片未做尺寸与格式控制，体积偏大； - 页面结构层级混乱，正文被大量嵌套容器包裹。 诊断结论是：渲染链路太长，且 HTML 本身不够“轻”。 ## 二、改造方向：让正文直接出现在 HTML 里 我们确定的核心原则是——**首屏正文应该在 HTML 返回时就存在，而不是等 JS 再拼出来**。围绕这一点做了几件事： 1. **预生成静态页**：把文档内容在构建阶段渲染为静态 HTML，请求时直接返回； 2. **精简 DOM**：用语义化标签替换无意义的多层 `div`，减少节点数量； 3. **脚本延迟加载**：交互脚本统一放到尾部或加 `defer`，不阻塞首屏； 4. **资源治理**：图片补全 `alt`、按需加载，样式与脚本做合并压缩。 在梳理语义结构时，我重新翻了 [HTML 入门教程](https://html.eapis.site/) 的基础章节，把标题层级、段落与链接的用法对照检查了一遍。它提到纯静态生成、无 JS 阻塞、自带 sitemap 与结构化数据的做法，和这次改造的目标几乎一致，也让我们更确认了方向没有跑偏。 ## 三、顺手补上的 SEO 基础 静态化不只是性能问题，也顺带解决了收录隐患： - 每个页面生成唯一 title 与 description； - 输出规范化 URL 并写入 sitemap； - 补齐面包屑与结构化标记； - 同主题文章之间建立内链。 页面组件和导航的排布，我们参考了 [Bootstrap 组件实验室](https://bootstrap.wanxiangsucai.com/) 中的面包屑、导航与卡片示例，用最少的结构把层级表达清楚，避免为了好看又堆回一堆脚本。 ## 四、效果与复盘 改造后，首屏白屏时间明显缩短，移动端体验改善最明显；更重要的是，蜘蛛能直接读到完整正文，抓取与收录的稳定性也随之提升。 复盘下来有三点体会： - **先测量再动手**，否则容易把优化做成猜测； - **结构优化收益常被低估**，语义化 DOM 对性能和可读性都有帮助； - **性能与 SEO 往往同源**，把 HTML 做轻、做清楚，两边都受益。 ## 结语 这次静态化改造没有用到什么高深技术，更多是把基础一件事件做对。当你发现页面又慢又难收录时，不妨先问一句：正文是不是在第一时间就直接可读？愿这份项目记录，能为你的下一次优化提供一个清晰的切入点。