企业官网建设流程全解析

• 前端
• 教程

本篇指南聚焦 Vercel React 最佳实践规则中的Hoist Static I/O to Module Level（将静态 I/O 提升至模块级），该规则收录于本仓库 .agents/skills/vercel-react-best-practices 技能包，是服务端性能（Server-Side Performance）类别中影响等级为 HIGH 的关键规则。阅读完本文，你将掌握如何在 Next.js 路由处理器（Route Handlers）与服务端函数中，把字体、Logo、配置与模板等静态资源的一次性加载提升到模块初始化阶段，彻底消除逐请求重复 I/O，并理解它与React.cache()、after()等兄弟规则在 AGENTS.md 优化体系中的定位与协作方式。

核心问题：为什么不能在请求内反复读静态资源

在 Next.js 的 Route Handlers（如app/api/og/route.tsx）或任意服务端函数中，每一次函数调用都会重新执行其内部的 I/O 语句。对于字体、Logo、图标、配置文件、邮件模板这类对所有请求内容完全一致的静态资产，逐请求读取是纯粹的浪费：

• 每次请求都触发一次文件系统读取（fs.readFile/fs.readFileSync）；
• 若资源托管在 CDN 或远程，则每次请求都发起一次网络 fetch；
• 两者都会放大响应延迟、增加函数实例的资源消耗，并抬高冷启动压力。

规则原文对此的定性非常明确：Impact: HIGH (avoids repeated file/network I/O per request)。其解决思路是：把 I/O 操作提升到模块（Module）级别。模块级代码在模块首次被 import 时执行且仅执行一次，而不是在每次请求调用时重复执行，从而把"每请求一次 I/O"降为"每实例一次 I/O"。

反例：每次请求都读取字体与 Logo

规则给出的第一个错误示例，是在 OG 图片生成路由中于请求函数内部读取字体与 Logo：

// app/api/og/route.tsx import { ImageResponse } from 'next/og' export async function GET(request: Request) { // Runs on EVERY request - expensive! const fontData = await fetch( new URL('./fonts/Inter.ttf', import.meta.url) ).then(res => res.arrayBuffer()) const logoData = await fetch( new URL('./images/logo.png', import.meta.url) ).then(res => res.arrayBuffer()) return new ImageResponse( <div style={{ fontFamily: 'Inter' }}> <img src={logoData} /> Hello World </div>, { fonts: [{ name: 'Inter', data: fontData }] } ) }

这段代码的问题在于：fetch及其后的arrayBuffer()位于GET函数体内，每一个请求都会重新下载并解析同样的 Inter.ttf 字体和 logo.png。对于高流量入口，这种重复开销会被直接放大到响应时间与函数计费中。

注意这里使用了new URL('./fonts/Inter.ttf', import.meta.url)来解析相对路径，这是 Next.js/ESM 环境下安全的资源定位方式——它基于当前模块的真实路径，而不是依赖不稳定的进程工作目录。

正例一：模块级启动 Promise，请求内仅 await

正确做法是把fetch提升到模块顶层，让 I/O在模块加载时立即开始，请求处理器内只需等待早已进行中的 Promise：

// app/api/og/route.tsx import { ImageResponse } from 'next/og' // Module-level: runs ONCE when module is first imported const fontData = fetch( new URL('./fonts/Inter.ttf', import.meta.url) ).then(res => res.arrayBuffer()) const logoData = fetch( new URL('./images/logo.png', import.meta.url) ).then(res => res.arrayBuffer()) export async function GET(request: Request) { // Await the already-started promises const [font, logo] = await Promise.all([fontData, logoData]) return new ImageResponse( <div style={{ fontFamily: 'Inter' }}> <img src={logo} /> Hello World </div>, { fonts: [{ name: 'Inter', data: font }] } ) }

这个版本的妙处在于双重收益：

1. I/O 只执行一次：两个fetch在模块首次 import 时就已经发起；
2. 天然的并行化：字体与 Logo 的加载互不依赖，模块顶层就同时启动，GET内再用Promise.all合并等待，与 async-api-routes 规则"尽早启动 Promise、尽晚 await"的理念完全一致。

正例二：模块级同步读取 fs

如果资源就位于服务器本地（例如public/fonts目录），且希望在模块初始化阶段一次性阻塞加载，可以使用同步读取。它只在模块首次加载时阻塞一次，之后的请求完全无 I/O 成本：

// app/api/og/route.tsx import { ImageResponse } from 'next/og' import { readFileSync } from 'fs' import { join } from 'path' // Synchronous read at module level - blocks only during module init const fontData = readFileSync( join(process.cwd(), 'public/fonts/Inter.ttf') ) const logoData = readFileSync( join(process.cwd(), 'public/images/logo.png') ) export async function GET(request: Request) { return new ImageResponse( <div style={{ fontFamily: 'Inter' }}> <img src={logoData} /> Hello World </div>, { fonts: [{ name: 'Inter', data: fontData }] } ) }

这里使用process.cwd()拼接到public下的静态目录，返回的是已完全加载好的Buffer，GET内不再有任何等待。代价是模块初始化阶段会同步阻塞事件循环，因此只适合在服务启动/实例初始化时一次性承担，换取后续所有请求的零 I/O。

反例与正例：请求内反复读配置与模板

除了资源文件，配置文件与模板也是高频受害者。规则给出的错误写法是每次调用都读取config.json与template.html：

import fs from 'node:fs/promises' export async function processRequest(data: Data) { const config = JSON.parse( await fs.readFile('./config.json', 'utf-8') ) const template = await fs.readFile('./template.html', 'utf-8') return render(template, data, config) }

正确写法同样把两个读取提升到模块级，并以 Promise 形式缓存：

import fs from 'node:fs/promises' const configPromise = fs .readFile('./config.json', 'utf-8') .then(JSON.parse) const templatePromise = fs.readFile('./template.html', 'utf-8') export async function processRequest(data: Data) { const [config, template] = await Promise.all([ configPromise, templatePromise, ]) return render(template, data, config) }

configPromise在模块加载时即开始读取并解析 JSON，templatePromise同步开始读取模板，请求函数内只做一次Promise.all合并等待。值得注意的是，即使首次请求还没完成，后续请求也会直接复用同一个已解析的 Promise 结果——Promise 状态只会流转一次（pending → fulfilled），天然充当了"模块级缓存"。

何时使用 / 何时禁用：适用边界

规则明确列出两套清单，帮助判断该模式是否适用：

推荐使用（When to use）：

• 为 OG 图片生成加载字体（fonts）；
• 加载静态 Logo、图标或水印；
• 读取运行时不会变化的配置文件；
• 加载邮件模板或其他静态模板；
• 任何在所有请求中内容完全一致的静态资产。

禁止或慎用（When not to use）：

• 随请求或用户变化的资产（必须按请求动态加载）；
• 运行时可能变更的文件（应改用带 TTL 的缓存策略，参见 server-cache-lru 跨请求 LRU 缓存）；
• 体积过大、常驻内存不可接受的大文件；
• 不应长期驻留内存的敏感数据（避免扩大数据暴露面）。

与兄弟规则的协作：完整服务端性能拼图

该规则并非孤立存在，它属于 vercel-react-best-practices 中第 3 优先级类别"Server-Side Performance（服务端性能）"，同类别还有多条互补规则，共同构成完整方案：

• server-cache-react：用React.cache()做单请求内去重（数据库查询、鉴权等非 fetch 异步任务），与本规则的"跨请求常驻"形成层次互补；
• server-cache-lru：对跨请求但会过期的数据使用 LRU 缓存（如 5 分钟 TTL），弥补静态提升方案对"运行时变更文件"的空白；
• async-api-routes：在 Route Handlers 与 Server Actions 中尽早启动独立 Promise、尽晚 await，与模块级 I/O 的并行理念同源；
• server-no-shared-module-state：强调不可变静态资产/一次性加载的配置可以在模块作用域驻留（即本规则场景），但请求相关的可变状态严禁放入模块级——两者共同划定了"模块级能放什么、不能放什么"的边界。

部署环境差异：Fluid Compute 与传统 Serverless

规则最后针对部署运行时给出了关键差异说明：

• Vercel Fluid Compute：多个并发请求共享同一函数实例，模块级加载的静态资产会在请求间持续驻留内存，没有冷启动惩罚，因此本模式收益最显著；
• 传统 Serverless：每次冷启动都会重新执行模块级代码，但后续的暖调用（warm invocation）会复用已加载的资产，直到实例被回收。

这意味着无论部署在哪种模型下，提升静态 I/O 都只会减少工作量而不会增加负担——最坏情况（冷启动）与请求内读取持平，最好情况（暖调用/共享实例）则把逐请求 I/O 完全省去。

在 React 面试语境中的价值

本项目 README.md 与 首页源码 表明该仓库定位为 React 技术面试问答（Preguntas de entrevista de React）。对于正在准备 Next.js/服务端性能方向的面试者，掌握本规则意味着能够回答并手写以下追问：

• "在 Route Handler 里加载字体，为什么不能在GET函数内每次 fetch？"——因为模块级代码只在首次 import 时执行一次，请求内 I/O 会逐请求重复；
• "模块级fetch与请求内fetch的 Promise 有何区别？"——模块级 Promise 状态只流转一次，天然充当跨请求缓存；
• "何时该用模块级同步readFileSync，何时该用 Promise 式fetch？"——取决于资源来源（本地 vs 远程）与初始化阻塞的容忍度；
• "它与React.cache()有何区别？"——React.cache()是单请求去重（见 server-cache-react），本规则是跨请求的模块常驻。

掌握"模块级 I/O 提升"这一模式，就掌握了服务端性能优化中成本收益比最高的技巧之一：改动极小、收益恒定，且与 Vercel Fluid Compute 的实例共享模型天然契合。

• 前端
• 教程