Next.js 13.5.6：pages目录小写.tsx文件build时不做类型检查

原因分析 #

Next.js 13.5.6的Pages Router在构建阶段的TypeScript类型检查逻辑存在文件名大小写敏感的问题：

• Pages目录作为路由核心目录，框架对其文件有特殊的构建处理逻辑。默认配置下，仅对大写开头的页面组件文件强制执行严格的TS类型校验；
• 小写开头的文件虽然能被VS Code的TypeScript服务识别并高亮错误，但Next.js的build流程未将其纳入强制类型检查范围，导致存在类型错误仍能完成构建；
• 该差异仅出现在Pages目录，是因为框架对普通目录的文件采用统一的类型检查规则，而Pages目录的文件受路由映射逻辑影响，检查规则不同。

解决方法 #

1. 强制全局类型检查（推荐） #

修改next.config.js，启用typescript.typeCheck配置，让Next.js在构建时对所有TS/TSX文件执行类型检查，不受文件名大小写限制：

/** @type {import('next').NextConfig} */
const nextConfig = {
  typescript: {
    typeCheck: true,
  },
};

module.exports = nextConfig;

开启后，npm run build会扫描所有符合tsconfig.json配置的文件，一旦发现类型错误就会终止构建。

2. 完善tsconfig.json配置 #

确保tsconfig.json的include字段覆盖Pages目录下的所有文件，并开启严格类型检查模式：

{
  "compilerOptions": {
    "strict": true,
    // 保留其他原有配置
  },
  "include": ["pages/**/*.ts", "pages/**/*.tsx", "components/**/*.ts", "components/**/*.tsx"],
  "exclude": ["node_modules"]
}

此配置需配合上述next.config.js的typeCheck: true使用，确保类型检查覆盖范围完整。

3. 统一页面文件名规范（可选） #

如果希望从根源避免此类问题，可通过ESLint强制Pages目录下的文件使用大写开头：

1. 安装依赖：

npm install eslint-plugin-filename-rules --save-dev

2. 修改.eslintrc.json添加规则：

{
  "plugins": ["filename-rules"],
  "rules": {
    "filename-rules/match": [
      "error",
      {
        "pages/**/*.tsx": "^[A-Z].*"
      }
    ]
  }
}

这样在开发阶段就能阻止小写开头的页面文件被创建，提前规避问题。

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