next16-expert

⚡ 技能：next16-expert

描述

Next.js 16.1.1 和 React 19.2 生态系统的高级专家。此技能专注于高性能的 Proxy 与缓存 范式、部分预渲染（PPR），以及从 middleware.ts 到 proxy.ts 的强制迁移。它提供适用于生产环境的现代全栈开发模式。

目录

1. 快速入门
2. Proxy 革命（proxy.ts）
3. 统一缓存（use cache）
4. React 19.2 模式
5. 数据获取与变更
6. 组件设计与单一职责
7. “禁止事项”列表（反模式）
8. 高级参考

---

快速入门

初始化一个精英级项目：

npx create-next-app@latest my-elite-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

精英级配置（next.config.ts）：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    ppr: true, // Enable Partial Pre-rendering
    dynamicIO: true, // New IO optimization for Next.js 16
    reactCompiler: true, // Stable React Compiler support
  },
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
};

export default nextConfig;

---

Proxy 革命（proxy.ts）

在 Next.js 16 中，middleware.ts 已是旧版方案。所有全局网络逻辑都必须放在 proxy.ts 中。这能稳定运行时，并为所有请求提供统一的入口。

标准精英级 Proxy（src/app/proxy.ts）：

import { nextProxy } from 'next/server';

export default nextProxy(async (request) => {
  const url = request.nextUrl;

  // Global Routing Logic
  if (url.pathname.startsWith('/api/v1')) {
    // Standardize API versioning at the proxy level
  }

  // Security Headers & Request Decoration
  request.headers.set('X-Elite-Engine', '16.1.1');
  
  const response = await fetch(request);

  // Performance Monitoring
  response.headers.set('Server-Timing', 'elite;dur=20');

  return response;
});

如需深入了解 A/B 测试和高级安全，请参阅 proxy-deep-dive.md。

---

统一缓存（use cache）

Next.js 16 引入了 use cache 指令，以显式的函数级缓存取代复杂的 revalidatePath。

缓存数据服务（src/services/data.ts）：

import { cacheLife, cacheTag } from 'next/cache';

export async function getGlobalMetrics() {
  'use cache';
  cacheLife(60); // Cache for 60 seconds
  cacheTag('metrics');

  const data = await fetch('https://api.internal/metrics').then(r => r.json());
  return data;
}

失效模式：

• revalidateTag('metrics')：立即清除。
• updateTag('metrics')：推荐。将其标记为过期，并在后台重新验证（SWR）。

如需了解复杂的缓存策略，请参阅 unified-caching.md。

---

React 19.2 模式

在 Next.js 16 中利用 React 19.2 的稳定性，减少样板代码。

1. 使用 useActionState 处理表单

在客户端组件中免去手动管理加载和错误状态。

'use client';
import { useActionState } from 'react';
import { signUpAction } from '@/actions/auth';

export function SignUpForm() {
  const [state, action, isPending] = useActionState(signUpAction, null);

  return (
    <form action={action}>
      <input name="email" type="email" required />
      {state?.errors?.email && <p className="text-red-500">{state.errors.email}</p>}
      
      <button disabled={isPending}>
        {isPending ? 'Processing...' : 'Sign Up'}
      </button>
    </form>
  );
}

2. <Activity /> 组件

用于预渲染后台标签页或隐藏的 UI，且不会产生性能开销。

import { Activity } from 'react';

export function TabSystem({ activeTab }) {
  return (
    <>
      <Activity mode={activeTab === 'home' ? 'visible' : 'hidden'}>
        <HomeTab />
      </Activity>
      <Activity mode={activeTab === 'settings' ? 'visible' : 'hidden'}>
        <SettingsTab />
      </Activity>
    </>
  );
}

---

数据获取与变更

服务端优先方案（RSC）

80% 的数据应在服务端组件中获取。

// app/dashboard/page.tsx
import { getGlobalMetrics } from '@/services/data';

export default async function Page() {
  const metrics = await getGlobalMetrics(); // Direct, cached call

  return (
    <div>
      <h1>Dashboard</h1>
      <pre>{JSON.stringify(metrics, null, 2)}</pre>
    </div>
  );
}

服务端操作（变更）

所有 POST/PATCH/DELETE 操作都必须使用。

// actions/auth.ts
'use server';
import { updateTag } from 'next/cache';

export async function signUpAction(prevState: any, formData: FormData) {
  const email = formData.get('email');
  
  try {
    await db.user.create({ data: { email } });
    updateTag('users'); // Background revalidation
    return { success: true };
  } catch (e) {
    return { errors: { email: 'Invalid email' } };
  }
}

---

组件设计与单一职责

• 300 行规则：组件文件应少于 300 行。如果组件超过此限制，请提取子组件，或将逻辑移至 hooks/ 或 services/。
• Hydration 防护：始终保护依赖浏览器专属状态的组件。

'use client';
import { useState, useEffect } from 'react';

export function SafeClientComponent({ children }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  if (!mounted) return <div className="animate-pulse" />; // Placeholder
  return <>{children}</>;
}

---

“禁止事项”列表（反模式）

• 不要使用 middleware.ts：请使用 proxy.ts。在 Next.js 16 中，middleware.ts 被视为旧版方案，性能也较差。
• 不要使用 revalidatePath 进行简单的 UI 更新：在服务端操作中使用 updateTag，以获得更好的用户体验（过期后重新验证）。
• 不要在没有 Suspense 的 RSC 中访问 cookies：访问 cookies() 或 headers() 会使路由变为动态。请将依赖这些内容的组件放入 <Suspense>，使页面其余部分保持静态（PPR）。
• 不要使用组件汇总文件（index.ts）：这会破坏 tree-shaking 并增大打包体积。请直接从组件文件导入。
• 不要硬编码 API URL：使用环境变量和 proxy.ts 层来管理不同环境。

---

高级参考

• 深入了解 Proxy — 高级路由与安全。
• 统一缓存 — 掌握 use cache 指令。
• React 专家 — 深入了解性能优化。
• Supabase 专家 — 后端与身份验证集成。

---

针对 Next.js 16.1.1 和 React 19.2 优化。更新于：2026 年 1 月 22 日 14:36