Next.js项目中npm run build正常运行但tsc报编译错误的问题咨询

Great question—this is a super common point of confusion with Next.js and TypeScript, since Next doesn’t use tsc directly under the hood for production builds. Let’s break down what’s going on, and how you can adjust things to match your preferences.

What Makes next build Behave Differently from Raw tsc #

Next.js has its own TypeScript integration that tweaks compiler options to balance type safety, runtime compatibility, and developer flexibility. Here are the biggest changes that usually suppress the errors you see when running tsc:

• Context-aware file exclusion: Next automatically skips strict type checking for files like next.config.js, middleware, and some edge runtime files—stuff that tsc will try to process if it’s in your include list.
• Relaxed strict mode defaults: Even if you set strict: true in your tsconfig.json, Next overrides some sub-options:
  • strictNullChecks: Often disabled in pages/routes where Next handles runtime defaults (like auto-loading layouts or props)
  • noImplicitAny: Softened for dynamic imports, server-side props, or cases where Next can infer types at runtime
  • skipLibCheck: Enabled by default, which skips type checking of external dependencies (this is a huge one—raw tsc often fails due to wonky types in @types packages)
• Incremental caching: Next uses incremental builds to cache type information, so it might skip full checks that tsc runs from scratch.
• Custom module resolution: Next has its own resolver for aliases, dynamic routes, and server/client components, avoiding resolution errors that tsc can’t handle.

Aligning next build and tsc to Match Your Preferences #

You mentioned you value compiler checks (totally fair—that’s why we use TypeScript!), but tsc is throwing too many errors while next build works. Let’s cover both scenarios: making next build as strict as tsc, or making tsc as permissive as next build.

Scenario 1: Make next build Strict Like tsc #

If you want next build to catch all the errors that tsc does (so you can enforce strict type safety in production), add this to your next.config.js:

module.exports = {
  typescript: {
    // Enable full strict type checking during builds
    strict: true,
    // Don't allow builds to pass if there are type errors (default is false)
    ignoreBuildErrors: false,
  },
};

You can also tweak your tsconfig.json to match the strict options tsc uses:

• Set skipLibCheck: false if you want to check external dependency types
• Ensure strictNullChecks: true and noImplicitAny: true are enabled
• Double-check your include/exclude rules match what tsc processes

Scenario 2: Make tsc as Permissive as next build #

If you want tsc to stop throwing those errors and behave like Next’s build process, update your tsconfig.json with these Next-like defaults:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "skipLibCheck": true,
    "strict": false, // Or enable specific strict options instead of all
    "noImplicitAny": false,
    "strictNullChecks": false,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    },
    "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
    "exclude": ["node_modules", ".next", "out"]
  }
}

Adding .next and out to your exclude list will match how Next ignores build artifacts, which can avoid unnecessary errors.

Quick Notes to Keep in Mind #

• Some errors tsc finds might be false positives in a Next context—Next’s runtime handles things like dynamic routes and server components in ways that raw TypeScript doesn’t understand.
• For development-time type checks, consider using next lint with the TypeScript ESLint plugin—it combines Next’s context-aware logic with strict linting rules, giving you the best of both worlds.

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