Gatsby构建时如何跳过错误页面，避免整体构建崩溃？

遇到Gatsby在Building static HTML for pages阶段页面创建失败，导致整个构建崩溃的情况？别慌，这里有几个实用的方案，帮你跳过错误页面，顺利完成构建：

1. 临时快速方案：用命令行参数跳过错误 #

如果只是需要紧急完成构建，不想花时间逐个排查页面错误，可以直接在构建命令里加上--no-fail-on-error参数：

gatsby build --no-fail-on-error

这个参数会告诉Gatsby：就算个别页面构建失败，也不要终止整个流程，继续完成其他正常页面的构建。失败的页面不会被生成，但不影响其他页面的产出，适合临时救急的场景。

2. 长期稳定方案：全局添加React错误边界 #

如果想保留页面（即使出错也显示友好的备用内容），同时避免构建崩溃，可以用React的错误边界特性，全局包裹所有页面组件。错误边界能捕获组件渲染时的错误，返回自定义备用UI，而不会让整个构建流程崩溃。

步骤1：创建错误边界组件 #

在src/components/ErrorBoundary.js里写一个错误边界组件：

import React from 'react';

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    // 更新状态，触发备用UI渲染
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    // 可以在这里记录错误日志，方便后续排查
    console.error(`页面渲染出错: ${error.message}`, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      // 自定义出错时显示的内容
      return (
        <div style={{ padding: '2rem', textAlign: 'center' }}>
          <h1>抱歉，这个页面加载失败了</h1>
          <p>我们正在修复这个问题，请稍后再试。</p>
        </div>
      );
    }

    return this.props.children;
  }
}

export default ErrorBoundary;

步骤2：全局包裹所有页面 #

在gatsby-browser.js里使用wrapPageElement API，让所有页面自动被错误边界包裹：

import React from 'react';
import ErrorBoundary from './src/components/ErrorBoundary';

export const wrapPageElement = ({ element, props }) => {
  return <ErrorBoundary {...props}>{element}</ErrorBoundary>;
};

这样一来，任何页面渲染出错时，都会被错误边界捕获，显示你定义的备用UI，而不会导致整个构建崩溃。

3. 精准控制：直接跳过有问题的页面创建 #

如果你已经明确知道哪些页面会出错（比如某些数据异常的动态页面），可以在gatsby-node.js的createPages阶段直接跳过这些页面的创建，从根源上避免构建错误。

比如，假设你从GraphQL获取的数据里有个标记字段isInvalid，用来判断页面是否有问题：

exports.createPages = async ({ actions, graphql }) => {
  const { createPage } = actions;

  // 获取页面数据源
  const queryResult = await graphql(`
    query GetPageData {
      allPageContent {
        nodes {
          id
          slug
          isInvalid # 标记是否为有问题的页面
        }
      }
    }
  `);

  if (queryResult.errors) {
    throw queryResult.errors;
  }

  queryResult.data.allPageContent.nodes.forEach(node => {
    // 跳过标记为无效的页面
    if (node.isInvalid) {
      console.log(`跳过错误页面: /${node.slug}`);
      return;
    }

    // 正常创建页面
    createPage({
      path: `/${node.slug}`,
      component: require.resolve('./src/templates/page-template.js'),
      context: { id: node.id },
    });
  });
};

这种方法最精准，完全避免了错误页面的构建流程，适合你能提前识别错误页面的场景。

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