Next.js 中间件未触发问题解决方案

问题描述

许多 Next.js 开发者在使用中间件时遇到一个常见问题：按照文档配置了 middleware.js 或 middleware.ts 文件，但中间件在实际访问时未被触发。具体表现为：

• 配置了路径匹配器（matcher）但未按预期重定向
• 中间件中的 console.log 语句未在终端输出
• 访问指定路由时显示 404 页面而非执行中间件逻辑

以下是一个典型的中间件配置示例：

export function middleware(request) {
  console.log('中间件被调用')
  return NextResponse.redirect(new URL('/', request.url))
}

export const config = {
  matcher: ['/test'],
}

解决方案

根据社区经验和官方文档，以下是解决 Next.js 中间件未触发问题的多种有效方法：

1. 正确的文件位置

根据 Next.js 版本不同，中间件文件的位置要求也不同：

Next.js 12+ 标准位置

// 项目根目录下的 middleware.js/ts
{root}/middleware.js

使用 src 目录时

// src 目录下的 middleware.js/ts
{root}/src/middleware.js

App Router 特殊情况

// Next.js 13+ 使用 App Router 时
{root}/src/middleware.js // 或根目录

TIP

从 Next.js 13.4 开始，官方推荐将中间件文件放置在项目根目录或 src 目录的根层级。

2. 文件命名检查

确保文件名拼写正确，常见错误包括：

• middlware.ts（缺少 e）
• middlware.js（拼写错误）
• middlewear.ts（字母顺序错误）

正确名称应为：middleware.js 或 middleware.ts

3. 配置 pageExtensions 的影响

如果在 next.config.js 中配置了 pageExtensions，中间件文件名也需要遵循相同的命名规则：

// next.config.js
const nextConfig = {
  pageExtensions: ["page.tsx", "api.ts"],
}

// 中间件文件名需要匹配配置
// middleware.page.ts 或 middleware.api.ts

4. 检查输出模式

如果使用静态导出（static export），中间件将无法工作：

// next.config.js - 这将禁用中间件
const nextConfig = {
  output: 'export', // 移除此行以启用中间件
}

5. 使用正确的导出方式

确保中间件使用默认导出：

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export default function middleware(request: NextRequest) {
  // 中间件逻辑
}

6. 终端而非浏览器控制台

中间件的日志输出在服务器终端（运行 npm run dev 的窗口），而不是浏览器控制台。

7. 版本特定解决方案

版本兼容性提示

不同版本的 Next.js 对中间件的支持有差异：

• Next.js 12-13.3：中间件文件应放置在项目根目录
• Next.js 13.4+：支持根目录和 src 目录两种位置
• Next.js 14+：官方文档推荐放置在根目录或 src 目录

8. 替代方案：next.config.js 重定向

如果中间件仍然无法工作，可以考虑使用 next.config.js 中的重定向功能作为临时解决方案：

// next.config.js
const nextConfig = {
  async redirects() {
    return [
      {
        permanent: true,
        source: "/test",
        destination: "/",
      },
    ];
  },
};

export default nextConfig;

调试步骤

1. 确认文件位置：检查中间件文件是否在正确位置
2. 检查文件名：确保没有拼写错误
3. 查看终端输出：运行 npm run dev 并观察终端日志
4. 验证配置：检查 next.config.js 中的相关设置
5. 更新 Next.js：考虑升级到最新稳定版本

总结

Next.js 中间件未触发的常见原因包括文件位置不正确、命名错误、配置冲突或版本兼容性问题。通过遵循上述解决方案，大多数情况下可以成功使中间件正常工作。

最佳实践

• 将中间件文件放置在项目根目录或 src 目录根层级
• 使用正确的文件名 middleware.js 或 middleware.ts
• 定期更新 Next.js 到最新稳定版本
• 在服务器终端而非浏览器控制台中查看日志

如果问题仍然存在，建议查阅 Next.js 官方中间件文档 或在 GitHub issues 中搜索类似问题。