配置trailingSlash: true时Next.js+GitHub Pages如何设置自定义404页面

• GitHub Pages默认仅会读取部署分支根目录下的404.html作为全站404 fallback页面，不会主动识别子目录下的/404/index.html文件
• 你对404.md的permalink配置存在认知偏差：该配置是Jekyll的专属语法，作用是指定该Markdown文件编译后生成的HTML输出路径，并非用来告知GitHub Pages 404页面的存放位置。如果你的Next.js部署流程中添加了.nojekyll文件（部署Next.js静态站的常规操作，用来避免Jekyll解析下划线开头的资源），该配置完全不会被解析，没有任何实际作用

下面两种方案都不会影响其他页面的无.html后缀路由规则，也不会干扰自定义域名的绑定配置：

方案1：打包后自动复制404文件到根目录 #

该方案不需要修改Next.js核心配置，实现成本最低：

1. 安装文件操作依赖：

npm install fs-extra --save-dev

2. 项目根目录新建postbuild.js脚本，内容如下：

const fs = require('fs-extra');

async function postBuild() {
  // 将打包生成的子目录404页面复制到根目录，命名为GitHub Pages要求的404.html
  await fs.copy('./out/404/index.html', './out/404.html');
}

postBuild();

3. 修改package.json的命令配置，添加打包后自动执行的钩子：

{
  "scripts": {
    "build": "next build",
    "postbuild": "node postbuild.js"
  }
}

方案2：配置Next.js导出规则直接生成根目录404文件 #

在next.config.js中添加导出路径配置，让打包时直接生成两份相同的404文件，同时满足你的路径规则和GitHub Pages的要求：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  trailingSlash: true,
  async exportPathMap(defaultPathMap) {
    return {
      ...defaultPathMap,
      '/404': { page: '/404' },
    }
  },
}

module.exports = nextConfig

配置完成后打包会同时生成根目录404.html和子目录/404/index.html，两边访问都正常。

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