Astro 7.4：构建诊断与并行预渲染

构建慢，先分清是在计算还是等待

内容站点接入 CMS、图片转换和交互组件之后，一次发布往往包含多种性质不同的工作。Markdown 编译主要消耗计算资源，远程取数可能被网络延迟拖住，图片编码又可能同时争用 CPU 与内存。它们最终都表现为“构建时间长”，对应的优化手段却不同。

因此，第一步应当是为同一提交、同一内容快照建立基线。固定 Node.js 版本、依赖锁文件和 CI 机器规格，把冷缓存与暖缓存的结果分开记录；否则，一次缓存命中就可能被误认成代码优化。下面给出的是验证方案，并非本文已经跑出的性能测试。

先找到耗时最大的阶段

在项目已有 Astro 依赖的情况下，可以执行：

npx astro build --timings

官方 CLI 文档确认，这个参数会在构建结束后列出阶段、Vite 插件、Markdown 与语法高亮、页面渲染、图片优化及集成钩子的耗时。应先观察哪一类工作占主导，再选择具体改动。CLI 参数说明

如果某类详情页很慢而目录页正常，可以继续检查它们共享的布局与数据调用。若主要时间落在图片处理，优先核查重复转换和输出规格；若慢的是插件转换，则要缩小插件处理范围。不要同时更换缓存策略、调整并发和删除插件，否则即使构建变快，也难以判断收益来自哪里。

页面并发与多线程是两层控制

原有的 build.concurrency 控制同时构建的页面数，默认值为 1。官方建议优先批量处理或缓存耗时任务，不要把增大这个数字作为常规优化。构建并发配置

理解它的关键在于：多个页面一起等待网络请求，与让多个 CPU 核心同时执行计算，并不是同一种能力。对于有串行依赖的请求，应先调整数据获取方式；对于重复读取同一份数据，应先减少重复工作。盲目加并发可能只是把等待变成远端限流。

从小规模 worker 配置开始

新的 experimental.parallelPrerender 使用 Node.js worker threads 分配静态页面渲染工作。可以先在测试分支采用保守配置：

import { defineConfig } from 'astro/config';

export default defineConfig({
  build: { concurrency: 1 },
  experimental: {
    parallelPrerender: { workers: 2 },
  },
});

这里的 2 是便于比较的起点，并非适用于所有机器的推荐值。默认启用时，Astro 会使用可用 CPU 核心数减一；增加 worker 也会增加内存消耗。页面渲染中的模块级变量不能视为跨 worker 共享缓存，包含函数或类实例等不可序列化值的 getStaticPaths() props 也受到限制。并行预渲染文档

基于这些约束，更合理的实验是保持页面并发不变，只比较关闭、多线程少量 worker、更多 worker 三种情况。同时观察峰值内存与外部 API 请求量。若耗时下降但偶发构建失败增加，就不能只按最快一次结果选择配置。

图像服务拆分后，要分别验收两条路径

混合渲染项目常把文章页预生成，把搜索或个性化页面留到请求时处理。两类页面对图片的处理时机不同，也可能运行在不同环境里。

现在 image.service 可以分别配置 build 与 runtime。前者负责预渲染页面图片，也用于开发模式；后者服务部署后的按需渲染页面和图像端点。预渲染图片在构建时由 Node 生成，因此构建阶段可以选择 Sharp。图像服务配置

这带来一个容易漏掉的验收点：本地开发页面正确，并不足以证明生产图像链路正确。团队应至少各选一张静态页图片和动态页图片，在部署预览中检查实际 URL、尺寸、格式、缓存响应和失败回退。若运行时使用外部图像服务，还应把其权限、配额及费用纳入评估；“构建更轻”可能伴随更多运行时请求，这是工程取舍，不是免费收益。

自定义图像服务也不只是一个返回地址的函数。官方区分本地转换服务和外部服务：前者可以承担实际图像转换，后者通常生成交给远端处理的 URL。选型时应明确转换究竟发生在哪里，避免把服务入口换掉后仍按原来的缓存与部署方式验收。图像服务 API

升级前先检查环境与集成契约

7.4 将 Astro 及官方集成的最低 Node.js 版本提高到 22.22.0。官方发布说明还提醒，相关项目应同步升级 @astrojs/cloudflare 与 @astrojs/markdoc；自定义预渲染器需要保留返回的图片元数据，旧式返回值虽然仍可使用，但已弃用，并可能导致对应页面图片不生成。Astro 7.4 发布说明

对维护集成的团队，这意味着升级测试必须覆盖产物，而不只是退出码：HTML 是否齐全、引用的图片是否真实存在、预渲染与按需页面是否均能访问，都应该逐项确认。

另外，使用自有预渲染机制的适配器不会受并行标志控制；官方文档明确列出的例外是 @astrojs/cloudflare。因此，看到配置存在不等于多线程已经生效，应检查构建警告与实际执行环境。适配器限制

把升级拆成可回退的三步

建议先完成运行环境与依赖升级，保留原有渲染配置，通过类型检查和部署预览；再使用耗时报告处理一个已定位的瓶颈；最后才引入实验性并行渲染，单独比较收益和资源成本。

验收记录至少包含提交与内容版本、机器规格、总耗时、慢页分布、峰值内存及产物检查结果。对于依赖外部接口的网站，还应记录请求数、失败率和限流情况。连续几次结果稳定，比某次跑得特别快更有参考价值。

构建优化最终服务于发布流程：需要缩短的是可预测的交付时间，同时保持内容、图片与动态路由正确。把观测、数据访问调整和并行执行分开验证，才能在出现回归时迅速定位，并回退最小的一处改动。