nextjs-validator

Next.js 验证器

验证 Next.js 16 配置，并防止使用已弃用的 Next.js 14/15 模式。

何时启用

• 搭建新的 Next.js 项目
• 开始任何 Next.js 开发工作前
• 审核现有 Next.js 项目
• AI 生成 Next.js 代码后
• CI/CD 流水线验证

快速开始

python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --strict

检查内容

1. 软件包版本

// GOOD: v16+
"next": "^16.0.0"

// BAD: v15 or earlier
"next": "^15.0.0"

2. Proxy 与 Middleware

正确 - Next.js 16：

// proxy.ts (Node.js runtime - REQUIRED)
import { createProxy } from 'next/proxy';
export const proxy = createProxy();

错误 - 已弃用：

// middleware.ts (Edge runtime - DEPRECATED)
export function middleware() { }

3. App Router 结构

正确：

app/
├── layout.tsx          # Root layout
├── page.tsx            # Home page
├── (routes)/           # Route groups
│   ├── dashboard/
│   │   └── page.tsx
│   └── settings/
│       └── page.tsx
└── api/                # API routes (optional)

错误 - Pages Router（已弃用）：

pages/
├── _app.tsx
├── index.tsx
└── api/

4. 缓存组件与 use cache

正确 - Next.js 16：

// app/dashboard/page.tsx
'use cache';

export default async function Dashboard() {
  const data = await fetch('/api/data');
  return <DashboardView data={data} />;
}

5. 服务端操作

正确：

// app/actions.ts
'use server';

export async function createItem(formData: FormData) {
  // Server-side logic
}

6. Turbopack 配置

正确 - Next.js 16 中的默认设置：

// next.config.ts (Turbopack is default, no config needed)

错误 - 禁用 Turbopack：

// Don't disable unless absolutely necessary
experimental: {
  turbo: false  // BAD
}

7. 配置文件格式

正确 - TypeScript 配置：

// next.config.ts
import type { NextConfig } from 'next';

const config: NextConfig = {
  // ...
};

export default config;

错误 - JavaScript 配置：

// next.config.js - Prefer .ts
module.exports = { }

应避免的已弃用模式

已弃用（v15-）	替代方案（v16+）
middleware.ts	proxy.ts
getServerSideProps	服务端组件 + use cache
getStaticProps	服务端组件 + use cache
getStaticPaths	generateStaticParams
_app.tsx	app/layout.tsx
_document.tsx	app/layout.tsx
pages/ 目录	app/ 目录
next/router	next/navigation
useRouter()（pages）	来自 next/navigation 的 useRouter()

应使用的 Next.js 16 功能

缓存组件

'use cache';

// Entire component cached
export default async function CachedPage() {
  const data = await fetchData();
  return <View data={data} />;
}

部分预渲染（PPR）

// next.config.ts
const config: NextConfig = {
  experimental: {
    ppr: true,
  },
};

Next.js DevTools MCP

借助上下文洞察进行 AI 辅助调试：

// Enable in development
// Works with MCP-compatible agent tools

并行路由

app/
├── @modal/
│   └── login/
│       └── page.tsx
├── @sidebar/
│   └── default.tsx
└── layout.tsx

拦截路由

目录布局请参阅 references/full-guide.md（§ 拦截路由示例）。

验证输出

报告示例请参阅 references/full-guide.md（§ 验证输出示例）。

迁移指南

迁移 middleware.ts → proxy.ts 和 getServerSideProps → 服务端组件的前后示例，请参阅 references/full-guide.md（§ 迁移指南）。

CI/CD 集成

# .github/workflows/validate.yml
- name: Validate Next.js 16
  run: |
    python3 scripts/validate.py \
      --root . \
      --strict \
      --ci

集成

• tailwind-validator - 验证 Tailwind v4 配置
• biome-validator - 验证 Biome 2.3+ 配置
• clerk-validator - 验证 Clerk 身份验证设置