Skip internal routes in middleware

Author: devjiwonchoi

packages/next/src/build/webpack-config.ts

@@ -2093,6 +2093,10 @@ export default async function getBaseWebpackConfig(
           dev,
           sriEnabled: !dev && !!config.experimental.sri?.algorithm,
           rewrites,
+          nextConfig: {
+            basePath: config.basePath,
+            skipMiddlewareNextInternalRoutes: config.skipMiddlewareNextInternalRoutes,
+          },
           edgeEnvironments: {
             __NEXT_BUILD_ID: buildId,
             NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: encryptionKey,

packages/next/src/build/webpack/plugins/middleware-plugin.ts

@@ -5,6 +5,7 @@ import type {
 import type { EdgeSSRMeta } from '../loaders/get-module-build-info'
 import type { MiddlewareMatcher } from '../../analysis/get-page-static-info'
 import { getNamedMiddlewareRegex } from '../../../shared/lib/router/utils/route-regex'
+import { getDefaultMiddlewareMatchers } from '../../../server/lib/router-utils/filesystem'
 import { getModuleBuildInfo } from '../loaders/get-module-build-info'
 import { getSortedRoutes } from '../../../shared/lib/router/utils'
 import { webpack, sources } from 'next/dist/compiled/webpack/webpack'
@@ -36,6 +37,7 @@ import type { CustomRoutes } from '../../../lib/load-custom-routes'
 import { isInterceptionRouteRewrite } from '../../../lib/generate-interception-routes-rewrites'
 import { getDynamicCodeEvaluationError } from './wellknown-errors-plugin/parse-dynamic-code-evaluation-error'
 import { getModuleReferencesInOrder } from '../utils'
+import type { NextConfig } from '../../../server/config-shared'
 
 const KNOWN_SAFE_DYNAMIC_PACKAGES =
   require('../../../lib/known-edge-safe-packages.json') as string[]
@@ -204,12 +206,17 @@ function getCreateAssets(params: {
       const { namedRegex } = getNamedMiddlewareRegex(matcherSource, {
         catchAll,
       })
-      const matchers = metadata?.edgeMiddleware?.matchers ?? [
-        {
-          regexp: namedRegex,
-          originalSource: page === '/' && catchAll ? '/:path*' : matcherSource,
-        },
-      ]
+
+      const matchers =
+        metadata?.edgeMiddleware?.matchers ??
+        (page === '/' && catchAll
+          ? getDefaultMiddlewareMatchers({
+              basePath: opts.nextConfig.basePath ?? '',
+              skipMiddlewareNextInternalRoutes: Boolean(
+                opts.nextConfig.skipMiddlewareNextInternalRoutes
+              ),
+            })
+          : [{ regexp: namedRegex, originalSource: matcherSource }])
 
       const isEdgeFunction = !!(metadata.edgeApiFunction || metadata.edgeSSR)
       const edgeFunctionDefinition: EdgeFunctionDefinition = {
@@ -818,17 +825,26 @@ interface Options {
   sriEnabled: boolean
   rewrites: CustomRoutes['rewrites']
   edgeEnvironments: EdgeRuntimeEnvironments
+  nextConfig: Pick<NextConfig, 'basePath' | 'skipMiddlewareNextInternalRoutes'>
 }
 
 export default class MiddlewarePlugin {
   private readonly dev: Options['dev']
   private readonly sriEnabled: Options['sriEnabled']
   private readonly rewrites: Options['rewrites']
   private readonly edgeEnvironments: EdgeRuntimeEnvironments
-
-  constructor({ dev, sriEnabled, rewrites, edgeEnvironments }: Options) {
+  private readonly nextConfig: Options['nextConfig']
+
+  constructor({
+    dev,
+    sriEnabled,
+    rewrites,
+    edgeEnvironments,
+    nextConfig,
+  }: Options) {
     this.dev = dev
     this.sriEnabled = sriEnabled
+    this.nextConfig = nextConfig
     this.rewrites = rewrites
     this.edgeEnvironments = edgeEnvironments
   }
@@ -886,6 +902,7 @@ export default class MiddlewarePlugin {
             rewrites: this.rewrites,
             edgeEnvironments: this.edgeEnvironments,
             dev: this.dev,
+            nextConfig: this.nextConfig,
           },
         })
       )

packages/next/src/server/config-schema.ts

@@ -689,6 +689,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
     serverExternalPackages: z.array(z.string()).optional(),
     serverRuntimeConfig: z.record(z.string(), z.any()).optional(),
     skipMiddlewareUrlNormalize: z.boolean().optional(),
+    skipMiddlewareNextInternalRoutes: z.boolean().optional(),
     skipTrailingSlashRedirect: z.boolean().optional(),
     staticPageGenerationTimeout: z.number().optional(),
     expireTime: z.number().optional(),

packages/next/src/server/config-shared.ts

@@ -1241,6 +1241,12 @@ export interface NextConfig {
 
   skipMiddlewareUrlNormalize?: boolean
 
+  /**
+   * Skip Next.js internals route `/_next` from middleware.
+   * @default true
+   */
+  skipMiddlewareNextInternalRoutes?: boolean
+
   skipTrailingSlashRedirect?: boolean
 
   modularizeImports?: Record<
@@ -1525,6 +1531,7 @@ export const defaultConfig = Object.freeze({
   },
   htmlLimitedBots: undefined,
   bundlePagesRouterDependencies: false,
+  skipMiddlewareNextInternalRoutes: true,
 } satisfies NextConfig)
 
 export async function normalizeConfig(phase: string, config: any) {

packages/next/src/server/lib/router-utils/filesystem.ts

@@ -31,6 +31,7 @@ import { pathHasPrefix } from '../../../shared/lib/router/utils/path-has-prefix'
 import { normalizeLocalePath } from '../../../shared/lib/i18n/normalize-locale-path'
 import { removePathPrefix } from '../../../shared/lib/router/utils/remove-path-prefix'
 import { getMiddlewareRouteMatcher } from '../../../shared/lib/router/utils/middleware-route-matcher'
+import type { MiddlewareMatcher } from '../../../build/analysis/get-page-static-info'
 import {
   APP_PATH_ROUTES_MANIFEST,
   BUILD_ID_FILE,
@@ -47,6 +48,34 @@ import { PrefetchRSCPathnameNormalizer } from '../../normalizers/request/prefetc
 import { encodeURIPath } from '../../../shared/lib/encode-uri-path'
 import { isMetadataRouteFile } from '../../../lib/metadata/is-metadata-route'
 
+/**
+ * Generate default middleware matchers that exclude /_next/ internal routes
+ */
+export function getDefaultMiddlewareMatchers(
+  config: Pick<
+    NextConfigComplete,
+    'basePath' | 'skipMiddlewareNextInternalRoutes'
+  >
+): MiddlewareMatcher[] {
+  // If skipMiddlewareNextInternalRoutes is explicitly set to false, match everything
+  if (config.skipMiddlewareNextInternalRoutes === false) {
+    return [{ regexp: '.*', originalSource: '/:path*' }]
+  }
+
+  const basePath = config.basePath || ''
+  // Build the exclusion regex directly - matches all paths except /_next/
+  const excludeRegex = basePath
+    ? `^${basePath}/(?!_next/).*$`
+    : `^/(?!_next/).*$`
+
+  return [
+    {
+      regexp: excludeRegex,
+      originalSource: '/((?!_next/).*)',
+    },
+  ]
+}
+
 export type FsOutput = {
   type:
     | 'appFile'
@@ -311,11 +340,15 @@ export async function setupFsCheck(opts: {
       middlewareMatcher = getMiddlewareRouteMatcher(
         middlewareManifest.middleware?.['/']?.matchers
       )
+    } else if (middlewareManifest.middleware?.['/']) {
+      // Middleware exists but has no matchers - use default with exclusions
+      middlewareMatcher = getMiddlewareRouteMatcher(
+        getDefaultMiddlewareMatchers(opts.config)
+      )
     } else if (functionsConfigManifest?.functions['/_middleware']) {
       middlewareMatcher = getMiddlewareRouteMatcher(
-        functionsConfigManifest.functions['/_middleware'].matchers ?? [
-          { regexp: '.*', originalSource: '/:path*' },
-        ]
+        functionsConfigManifest.functions['/_middleware'].matchers ??
+          getDefaultMiddlewareMatchers(opts.config)
       )
     }
 

packages/next/src/server/lib/router-utils/setup-dev-bundler.ts

@@ -14,7 +14,7 @@ import path from 'path'
 import qs from 'querystring'
 import Watchpack from 'next/dist/compiled/watchpack'
 import findUp from 'next/dist/compiled/find-up'
-import { buildCustomRoute } from './filesystem'
+import { buildCustomRoute, getDefaultMiddlewareMatchers } from './filesystem'
 import * as Log from '../../../build/output/log'
 import { setGlobal } from '../../../trace/shared'
 import type { Telemetry } from '../../../telemetry/storage'
@@ -471,9 +471,11 @@ async function startWatcher(
             'actualMiddlewareFile',
             serverFields.actualMiddlewareFile
           )
-          middlewareMatchers = staticInfo.middleware?.matchers || [
-            { regexp: '^/.*$', originalSource: '/:path*' },
-          ]
+          middlewareMatchers = staticInfo.middleware?.matchers ||
+            getDefaultMiddlewareMatchers({
+              basePath: nextConfig.basePath,
+              skipMiddlewareNextInternalRoutes: nextConfig.skipMiddlewareNextInternalRoutes
+            })
           continue
         }
         if (isInstrumentationHookFile(rootFile)) {