Next.js 15 核心功能代码示例详解

一、React 19 与核心功能

1. React 19 新特性使用

use Hook 现在可以直接在客户端组件中处理 Promise
Suspense 边界变得更加智能，可以更好地处理加载状态
sibling pre-warming 特性可以预热相邻组件提升性能

// app/components/AsyncComponent.tsx
'use client';

import { use } from 'react';

function AsyncComponent({ promise }: { promise: Promise<any> }) {
  const data = use(promise); // React 19 新的 use Hook
  return <div>{data}</div>;
}

// app/page.tsx
export default function Page() {
  const promise = fetch('/api/data');
  return (
    <Suspense fallback={<Loading />}>
      <AsyncComponent promise={promise} />
    </Suspense>
  );
}

2. 新的缓存系统

use cache 指令提供了更直观的缓存控制方式
cacheTag 支持更细粒度的缓存管理
cacheLife 允许精确控制缓存的生命周期，从秒级到周级都支持

// app/utils/data.ts
async function fetchData() {
  'use cache'; // 新的缓存指令

  const res = await fetch('https://api.example.com/data');
  return res.json();
}

// 带标签的缓存
import { cacheTag } from 'next/cache';

async function getCachedData() {
  'use cache';
  cacheTag('my-data');
  return fetchData();
}

// 缓存生命周期控制
import { unstable_cacheLife as cacheLife } from 'next/cache';

export default async function Page() {
  'use cache';
  cacheLife("hours");
  return <Component />;
}

3. 错误处理

错误边界现在可以更好地处理服务端和客户端错误
支持更详细的错误信息展示
提供了更好的错误重试机制

// app/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div className="error-container">
      <h2>出错了！</h2>
      <p>{error.message}</p>
      <button onClick={reset}>重试</button>
    </div>
  );
}

二、Turbopack 配置

1. 开发服务器配置

Turbopack 现已完全稳定，可以安全用于生产环境
支持大多数 webpack 加载器，迁移成本较低
构建速度提升显著，特别是在大型项目中

// next.config.ts
const nextConfig = {
  experimental: {
    turbo: {
      loaders: {
        // 自定义加载器配置
        '.svg': ['@svgr/webpack'],
      },
      resolveAlias: {
        // 路径别名
        '@/*': ['./src/*'],
      },
    },
  },
};

// 使用 Turbopack
// package.json
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

2. 热重载优化

支持智能的增量编译
提供更快的热更新响应
内存占用得到显著优化

// app/components/DynamicComponent.tsx
'use client';

import { useEffect, useState } from 'react';

export default function DynamicComponent() {
  const [data, setData] = useState(null);

  useEffect(() => {
    // Turbopack 会优化这类数据获取
    fetch('/api/data')
      .then(res => res.json())
      .then(setData);
  }, []);

  return <div>{JSON.stringify(data)}</div>;
}

三、认证与授权系统

1. 新的认证错误处理

提供了更标准化的错误处理流程
可以自定义错误页面，提升用户体验
支持中间件层面的认证控制

// app/middleware.ts
import { NextResponse } from 'next/server';
import { unauthorized, forbidden } from 'next/navigation';

export async function middleware(request) {
  const session = await getSession(request);
  
  if (!session) {
    unauthorized();
  }

  const hasAccess = await checkAccess(session);
  if (!hasAccess) {
    forbidden();
  }

  return NextResponse.next();
}

// app/unauthorized.tsx
export default function Unauthorized() {
  return (
    <div className="auth-error">
      <h2>需要登录</h2>
      <LoginButton />
    </div>
  );
}

// app/forbidden.tsx
export default function Forbidden() {
  return (
    <div className="auth-error">
      <h2>访问被拒绝</h2>
      <BackButton />
    </div>
  );
}

2. after API 使用

适合处理不影响响应时间的后台任务
支持复杂的异步操作
可以与各种分析和日志系统集成

// app/actions.ts
import { after } from 'next/server';
import { cookies } from 'next/headers';

export async function handleFormSubmission(formData: FormData) {
  const result = await processForm(formData);

  after(async () => {
    const cookieStore = cookies();
    await Analytics.track('form_submission', {
      userId: cookieStore.get('user_id'),
      formData: formData
    });
  });

  return result;
}

四、性能优化与部署

1. 图片优化配置

自动针对不同设备优化图片尺寸
支持现代图片格式如 WebP
提供灵活的缓存控制选项

// next.config.ts
const nextConfig = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    formats: ['image/webp'],
    minimumCacheTTL: 60,
    dangerouslyAllowSVG: true,
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
};

2. 性能监控

支持核心 Web 指标的自动收集
可以与主流监控系统集成
提供详细的性能数据分析

// app/monitoring/index.ts
import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals(metric => {
    const { id, name, label, value } = metric;
    
    // 发送到分析服务
    analytics.track('web_vitals', {
      id,
      name,
      label,
      value,
      timestamp: Date.now()
    });
  });

  return null;
}

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { setupMonitoring } = await import('./monitoring');
    await setupMonitoring({
      metricsEndpoint: process.env.METRICS_ENDPOINT,
      errorTracking: true,
    });
  }
}

3. 构建优化

支持增量静态重新生成
提供灵活的依赖处理选项
优化了静态资源的处理流程

// next.config.ts
const nextConfig = {
  output: 'standalone',
  experimental: {
    // 构建优化
    optimizeCss: true,
    optimizePackageImports: ['lodash', 'date-fns'],
    
    // 并行构建
    parallelBuild: true,
    
    // 外部包处理
    serverExternalPackages: [
      'sharp',
      'some-large-package',
    ],
    
    // 静态页面生成控制
    staticGenerationRetryCount: 3,
    staticGenerationMaxConcurrency: 8,
  },
  
  // 压缩配置
  compress: true,
  
  // 缓存控制
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, max-age=31536000, immutable',
          },
        ],
      },
    ];
  },
};

export default nextConfig;

4. 路由和布局优化

支持嵌套布局和并行路由
提供更好的国际化支持
优化了导航性能

// app/layout.tsx
import { Suspense } from 'react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh">
      <body>
        <Header />
        <Suspense fallback={<GlobalLoadingSpinner />}>
          <main>{children}</main>
        </Suspense>
        <Footer />
      </body>
    </html>
  );
}

// app/[locale]/layout.tsx
export default async function LocaleLayout({
  children,
  params: { locale },
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const messages = await getTranslations(locale);
  
  return (
    <LocaleProvider locale={locale} messages={messages}>
      {children}
    </LocaleProvider>
  );
}

这些代码示例展示了 Next.js 15 各个核心功能的具体实现方式。每个示例都包含了必要的注释和最佳实践建议。这些代码可以作为项目实施的参考基础。

需要我对某个具体功能的实现做更详细的解释吗？