配置Next.js pageExtensions，排除*.dev.*页面参与生产构建

问题背景 #

在Next.js 12.3项目中，需要实现：生产环境构建时自动排除带*.dev.*扩展名的页面文件，开发环境则正常加载这类页面。当前通过pageExtensions按环境配置后，所有页面均返回404错误。

问题根源 #

1. 全局页面文件未适配自定义扩展名：设置pageExtensions后，Next.js只会识别符合该扩展名规则的文件作为页面。如果_app.tsx、_document.tsx等全局文件未按规则重命名（比如未添加.page后缀），会导致路由系统完全失效，所有页面返回404。
2. 需确保pageExtensions配置与实际文件命名规则严格匹配。

解决方案 #

1. 统一页面文件命名规则 #

• 生产环境页面：命名为[页面名].page.tsx/[页面名].page.ts（如home.page.tsx）
• 开发专属页面：命名为[页面名].dev.page.tsx/[页面名].dev.page.ts（如debug.dev.page.tsx）
• 全局页面文件：将_app.tsx重命名为_app.page.tsx，_document.tsx重命名为_document.page.tsx（若使用）

2. 修正next.config.js配置 #

简化并确认环境判断逻辑，确保开发环境添加专属扩展名：

const withTM = require('next-transpile-modules')(['ui']);
const { PHASE_DEVELOPMENT_SERVER } = require('next/constants');

module.exports = withTM((phase) => {
  const isDev = phase === PHASE_DEVELOPMENT_SERVER;
  
  let pageExtensions = ['page.tsx', 'page.ts'];
  
  if (isDev) {
    // 开发环境加入开发专属页面扩展名
    pageExtensions = [...pageExtensions, 'dev.page.tsx', 'dev.page.ts'];
  }

  return {
    i18n: {
      locales: ['en-US'],
      defaultLocale: 'en-US',
    },
    pageExtensions,
    reactStrictMode: true,
    images: {
      domains: ['cdn.sanity.io'],
    },
  };
});

3. 验证配置效果 #

• 开发环境：运行npm run dev，访问开发专属页面（如/debug）及普通页面均能正常加载。
• 生产环境：运行npm run build，检查构建产物确认*.dev.page.*文件未被包含；启动生产服务后，开发专属页面返回404（符合预期），普通页面正常访问。

补充说明 #

如果不想给全局文件添加.page后缀，可在pageExtensions中保留原扩展名（如生产环境设为['tsx', 'ts', 'page.tsx', 'page.ts']），但这样会导致普通.tsx文件被当作页面，建议统一使用.page后缀区分页面与组件文件。

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