配合框架编译器的静态HTML生成与水合优化-html教程-PHP中文网

generatestaticparams 与 dynamic="force-static" 需配合使用：前者在动态路由段返回预生成路径对象数组，后者强制组件走ssg路径但需前者提供参数；单独使用后者会报“no routes matched”错误。

配合框架编译器的静态html生成与水合优化

用错组合会导致页面不生成、水合失败或 fallback 到 CSR。关键不是“要不要静态”，而是“谁来决定静态时机”。

generateStaticParams 只在 App Router 的动态路由段（如 [slug]）中生效，返回一个对象数组，每个对象对应一个预生成路径；它不触发水合，只告诉编译器“这些路径要提前吐 HTML”
dynamic = "force-static" 是组件级指令，写在 Server Component 顶部，强制该组件及其子树走 SSG 路径；但它本身不提供参数列表，必须配合 generateStaticParams 或 generateStaticParams 才能落地
常见错误：在 layout.tsx 或根 page.tsx 里写 dynamic = "force-static" 却没配 generateStaticParams → 构建时报 Error: No routes matched，因为编译器找不到可展开的路径
性能影响：二者配合后，Next.js 会在构建时生成完整 HTML + JSON 数据块（.json 后缀），客户端 hydrate 时直接读取，避免重复 fetch；但若 JSON 数据过大（>100KB），会拖慢首屏解析

不是所有带交互的元素都得立刻 hydrate —— 水合粒度错，TTI 就白优化了。

html-to-pptx

将多页 HTML 演示文稿转换为美化的 PPTX 文件，便于分享和分发。

下载

默认行为：只要用了 use client 的组件，其整个子树（包括纯展示节点）都会被 React 客户端接管并 hydrate；哪怕里面只有一个 button，旁边 div 里的文字也会参与 diff
真正该 hydrate 的只有：绑定事件的节点（onClick、onChange）、受控输入（value + onChange）、依赖客户端状态的条件渲染分支（如 showModal && <modal></modal>）
容易踩的坑：把 use client 放在布局组件顶层，导致页脚、侧边栏等静态区块也被强制 hydrate；应下沉到最小交互单元，比如只包住 CartButton，而不是整个 Header
验证方式：打开 DevTools → Elements 面板，右键节点 → “Break on” → “attribute modifications”，再刷新页面；如果非交互节点频繁触发断点，说明水合范围过大

静态生成阶段没有运行时环境，fetch 失败不是 bug，是设计使然 —— 关键是怎么让它“安静地失败”。

不要在 Server Component 中裸写 await fetch(...)；必须加 cache: "force-cache" 或 next: { revalidate: 0 }，否则 Next.js 默认走 dynamic fetch，构建时报 fetch failed during build
fallback 数据不能靠 try/catch 包裹 fetch 来实现 —— 构建时 catch 会吞掉错误但不提供替代值；正确做法是用 process.env.NODE_ENV === "production" 判断环境，开发时用 mock 数据，构建时用预置 JSON 文件（如 public/fallback/products.json）
路径问题：SSG 期间 fetch 目标地址必须是绝对 URL（https://api.example.com），相对路径（/api/products）会被解析成 http://localhost:3000/api/products，而构建时本地服务根本没跑
体积代价：每个 fallback JSON 文件都会打进 dist/，若单个超 500KB，建议拆成按需加载的 data-[id].json，并在客户端用 useEffect 补充加载

这个属性是局部水合的锚点，但手动生成 ID 容易重复，框架自动生成又难调试。

Next.js 不暴露 data-hydrate-id 的控制权，它由 React.createElement 在 SSR 阶段注入，格式类似 data-hydrate-id="0.1.2.3"；你不能改，也不该改
真正要管的是“水合边界” —— 用 useId() 生成稳定 key，再结合 data-island 标记，比如：<div data-island="search-bar" data-id="{id}">，然后在 hydrate.js 里查 <code>document.querySelectorAll('[data-island="search-bar"]')
冲突高发场景：多个微应用共用同一主容器，各自 hydrate 逻辑扫描全局 data-hydrate-id → 互相覆盖；解法是主容器加命名空间前缀，如 data-hydrate-id="cart-0.1.2"，微应用 hydrate 时限定查询范围
别依赖它做状态同步 —— data-hydrate-id 只用于 DOM 绑定，props 必须走 data-props 注入，且 JSON 字符串需 encodeURIComponent 编码，否则含引号或换行会破坏 HTML 结构