fix(#36855/#30300): export 404.html correctly

packages/next/export/index.ts

@@ -418,13 +418,20 @@ export default async function exportApp(
         })
       )
 
-    if (
-      !options.buildExport &&
-      !exportPathMap['/404'] &&
-      !exportPathMap['/404.html']
-    ) {
-      exportPathMap['/404'] = exportPathMap['/404.html'] = {
-        page: '/_error',
+    // only add missing 404 page when `buildExport` is false
+    if (!options.buildExport) {
+      // only add missing /404 if not specified in `exportPathMap`
+      if (!exportPathMap['/404']) {
+        exportPathMap['/404'] = { page: '/_error' }
+      }
+
+      /**
+       * exports 404.html for backwards compat
+       * E.g. GitHub Pages, GitLab Pages, Cloudflare Pages, Netlify
+       */
+      if (!exportPathMap['/404.html']) {
+        // alias /404.html to /404 to be compatible with custom 404 / _error page
+        exportPathMap['/404.html'] = exportPathMap['/404']
       }
     }
 

test/integration/export-404/next.config.js

@@ -0,0 +1,5 @@
+module.exports = (phase) => {
+  return {
+    trailingSlash: false,
+  }
+}

test/integration/export-404/test/index.test.js

@@ -0,0 +1,51 @@
+/* eslint-env jest */
+
+import { promises } from 'fs'
+import { join } from 'path'
+import { nextBuild, nextExport, File } from 'next-test-utils'
+
+const { readFile, access, stat } = promises
+const appDir = join(__dirname, '../')
+const outdir = join(appDir, 'out')
+
+const nextConfig = new File(join(appDir, 'next.config.js'))
+
+const fileExist = (path) =>
+  access(path)
+    .then(() => stat(path))
+    .then((stats) => (stats.isFile() ? true : false))
+    .catch(() => false)
+
+// Issue #36855
+// https://github.com/vercel/next.js/issues/36855
+describe('Static 404 Export', () => {
+  it('only export 404.html when trailingSlash: false', async () => {
+    await nextBuild(appDir)
+    await nextExport(appDir, { outdir })
+
+    expect(await fileExist(join(outdir, '404.html'))).toBe(true)
+    expect(await fileExist(join(outdir, '404.html.html'))).toBe(false)
+    expect(await fileExist(join(outdir, '404/index.html'))).toBe(false)
+  })
+
+  it('export 404.html and 404/index.html when trailingSlash: true', async () => {
+    nextConfig.replace(`trailingSlash: false`, `trailingSlash: true`)
+    await nextBuild(appDir)
+    await nextExport(appDir, { outdir })
+    nextConfig.restore()
+
+    expect(await fileExist(join(outdir, '404/index.html'))).toBe(true)
+    expect(await fileExist(join(outdir, '404.html.html'))).toBe(false)
+    expect(await fileExist(join(outdir, '404.html'))).toBe(true)
+  })
+})
+
+describe('Export with a page named 404.js', () => {
+  it('should export a custom 404.html instead of default 404.html', async () => {
+    await nextBuild(appDir)
+    await nextExport(appDir, { outdir })
+
+    const html = await readFile(join(outdir, '404.html'), 'utf8')
+    expect(html).toMatch(/this is a 404 page override the default 404\.html/)
+  })
+})