Next.js中publicRuntimeConfig能否结合静态生成？文档疑义解析

核心结论 #

可以在静态生成（SSG）页面中使用publicRuntimeConfig，但存在功能限制，且官方明确不推荐这种用法。

文档含义解析 #

你看到的两段文档描述其实并不矛盾，只是针对不同场景：

• 第一段的“与自动静态优化不兼容”：
  这里指的是动态运行时的publicRuntimeConfig无法和自动静态优化共存。如果你的publicRuntimeConfig是服务器端运行时动态生成的（比如根据服务器环境变量、数据库配置动态获取），静态生成的页面在客户端渲染时无法拿到这些动态值——因为SSG页面在构建阶段就已生成静态文件，没有服务器端渲染步骤注入最新的运行时配置。

• 第二段的“必须退出自动静态优化才能生效”：
  同样针对动态运行时配置场景。如果依赖动态的publicRuntimeConfig，必须通过getInitialProps、getServerSideProps或带getInitialProps的自定义App触发服务端渲染，确保每次请求都能注入最新的运行时配置。如果不退出静态优化，客户端拿到的静态页面无法获取动态更新的配置值。

你的测试代码能正常运行，是因为你的publicRuntimeConfig是在next.config.js中静态配置的固定值——Next.js会在构建时将这类静态配置注入到客户端的__NEXT_DATA__对象中，所以静态生成页面的客户端能正常读取。但这种场景下，publicRuntimeConfig和构建时环境变量（process.env.NEXT_PUBLIC_*）的效果完全一致，官方更推荐后者。

为何不推荐使用运行时配置 #

• 性能开销：运行时配置需要在客户端初始化阶段从__NEXT_DATA__或服务器请求中读取，增加了页面渲染/初始化的额外耗时；而构建时环境变量会直接嵌入到编译后的代码中，无需额外读取步骤，性能更优。
• 静态优化限制：一旦依赖动态运行时的publicRuntimeConfig，就必须放弃自动静态优化，改用服务端渲染（SSR），失去了SSG页面快速加载、可缓存的核心优势。
• 维护复杂度：运行时配置和构建时配置的生效逻辑不同，动态配置的变更需要重启服务器，而构建时配置需要重新构建项目，容易引发混淆和排查问题的成本。

实践建议 #

• 如果你的配置值是固定不变的，直接使用process.env.NEXT_PUBLIC_*构建时环境变量，避免不必要的运行时开销。
• 如果配置值需要动态更新，则必须使用getServerSideProps或getInitialProps触发服务端渲染，确保每次请求都能获取最新配置，但此时页面无法静态生成。

内容的提问来源于stack exchange，提问作者ptf