如何在Next.js中为CloudFront+S3部署的URL添加.html后缀？

问题背景 #

你的场景是Next.js静态导出后部署在S3+CloudFront环境，未使用CloudFront Functions，导致非根目录路径（如/about）无法直接访问，必须访问/about.html才能正常加载。仅设置trailingSlash: false无效，因为该配置仅控制路径斜杠，不会自动添加.html后缀。

解决方案分两种路由场景处理： #

1. Pages Router（Next.js 12及以下）

步骤1：修改next.config.js配置导出路径

通过exportPathMap自定义导出的文件路径，让非根路由生成带.html后缀的文件：

module.exports = {
  trailingSlash: false,
  exportPathMap: async (defaultPathMap) => {
    const pathMap = {};
    Object.keys(defaultPathMap).forEach(path => {
      if (path === '/') {
        // 根目录保留index.html
        pathMap['/'] = defaultPathMap[path];
      } else {
        // 为非根路由添加.html后缀
        pathMap[`${path}.html`] = defaultPathMap[path];
        // 可选：保留原路径映射，兼容内部未修改的链接（按需选择）
        pathMap[path] = defaultPathMap[path];
      }
    });
    return pathMap;
  }
};

步骤2：自定义Link组件统一链接格式

Next.js默认的Link组件生成不带.html的链接，需替换为自定义组件确保所有内部链接带后缀：

import Link from 'next/link';

const CustomLink = ({ href, ...props }) => {
  const formattedHref = href === '/' ? href : `${href}.html`;
  return <Link href={formattedHref} {...props} />;
};

export default CustomLink;

之后项目中所有跳转链接都使用CustomLink替代原生Link。

2. App Router（Next.js 13+）

步骤1：基础配置next.config.js

开启静态导出模式并关闭尾斜杠：

module.exports = {
  output: 'export',
  trailingSlash: false,
  assetPrefix: './', // 配置相对路径加载静态资源
};

步骤2：编写postbuild脚本重命名文件

App Router默认会为每个路由生成[路由名]/index.html结构，需通过脚本将其重命名为[路由名].html：

1. 在项目根目录创建scripts/rename-html-files.js：

const fs = require('fs').promises;
const path = require('path');

async function renameHtmlFiles(dir) {
  const entries = await fs.readdir(dir, { withFileTypes: true });
  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      const indexHtmlPath = path.join(fullPath, 'index.html');
      try {
        await fs.access(indexHtmlPath);
        // 将index.html重命名为对应目录名的html文件
        await fs.rename(indexHtmlPath, path.join(dir, `${entry.name}.html`));
        // 删除空目录
        await fs.rmdir(fullPath);
      } catch (err) {
        // 目录下无index.html，递归处理子目录
        await renameHtmlFiles(fullPath);
      }
    }
  }
}

async function main() {
  const outDir = path.join(__dirname, '../out');
  await renameHtmlFiles(outDir);
}

main().catch(console.error);

2. 在package.json的scripts中添加postbuild命令：

"scripts": {
  "build": "next build",
  "postbuild": "node scripts/rename-html-files.js"
}

步骤3：自定义客户端Link组件

同样需要替换原生Link，确保链接带.html后缀：

'use client';
import Link from 'next/link';

export default function CustomLink({ href, ...props }) {
  const formattedHref = href === '/' ? href : `${href}.html`;
  return <Link href={formattedHref} {...props} />;
}

验证效果 #

执行npm run build后，out目录下会生成带.html后缀的文件（如about.html），内部链接也会自动添加后缀，部署到S3+CloudFront后，访问/about.html即可正常加载页面。

内容的提问来源于stack exchange，提问作者masami.nishide