Next.js中getStaticProps抛错但构建仍成功的原因咨询

我有一个位于旧Pages目录（非新版App Router）的Next.js页面，代码如下：

export const getStaticProps = async (...args) => {
    throw new Error('error inside');
}
throw new Error('error outside');

const SomePage = () => (<div/>);
export default SomePage;

构建应用时，外部抛出的error outside会导致构建失败，符合预期。但移除该行错误后，尽管getStaticProps内仍抛出error inside，构建却能成功完成。

我原以为getStaticProps会在构建阶段运行，官方文档也明确说明“getStaticProps always runs during next build”，但实际情况却与此不符，对此感到困惑。

补充背景：我有部分路由在构建时无数据，但开发模式下正常。调试时发现，getStaticProps内的日志无法在构建控制台显示，仿佛该函数未执行；但移除getStaticProps时，会出现“getStaticPaths was added without a getStaticProps”的错误，说明函数被Next.js识别，但并未触发执行。

核心原因：getStaticProps仅在需要预渲染的场景下才会在构建阶段执行 #

官方文档的描述有前提——getStaticProps仅当页面需要在构建阶段被预渲染时，才会执行。如果你的页面满足以下情况，构建阶段不会触发getStaticProps：

• 动态路由 + getStaticPaths返回空paths数组
  如果你的页面是动态路由（比如[slug].js）且配置了getStaticPaths，当getStaticPaths返回的paths为空，同时fallback设置为true或'blocking'时，Next.js在构建阶段不会生成任何预渲染页面，自然也不会执行getStaticProps。只有当用户首次访问某个动态路径时，才会临时执行getStaticProps生成页面。这就解释了为什么构建时getStaticProps内的错误不会导致构建失败，日志也不会输出——因为函数根本没在构建阶段运行。

• 动态路由 + fallback: true/blocking但无预渲染路径
  这种场景下，Next.js会在构建阶段跳过getStaticProps的执行，把页面的生成延迟到用户访问时。此时构建过程不会检测getStaticProps内的错误，因为没有预渲染任务需要执行。

验证与解决方法 #

1. 检查页面是否为动态路由，查看getStaticPaths的返回值：
   如果paths为空数组，且fallback不是false，那就是上述场景导致的问题。若需要在构建阶段验证getStaticProps的逻辑，可以临时添加一条测试路径到paths中，构建时Next.js会执行该路径对应的getStaticProps，此时错误就会触发构建失败。

2. 静态路由的特殊情况：
   如果是普通静态页面（非动态路由）但getStaticProps仍未执行，需要检查是否配置了增量静态再生（ISR）或其他阻止预渲染的设置。不过这种情况相对少见，多数场景还是动态路由配合空paths导致的。

关于文档描述的补充 #

官方文档中“getStaticProps always runs during next build”的完整逻辑是：当页面需要在构建阶段生成静态HTML时，getStaticProps一定会执行。但对于不需要预渲染的动态路由场景，Next.js会延迟getStaticProps的执行时机，因此不会在构建阶段触发。

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