第 35 讲：Next.js 应用性能优化清单（Bundle / TTFB / LCP / INP）

export async function printTreeView(...) {
  // 输出每条 route 的 size / First Load JS / ISR 标记
}

Route (app)                                  Size     First Load JS
┌ ○ /                                        135 B          85 kB
├ ○ /_not-found                              868 B          86 kB
├ ƒ /api/posts                               0 B                0 B
├ ● /blog/[slug]                             1.2 kB         95 kB
└ ƒ /admin/dashboard                         8.4 kB        140 kB
+ First Load JS shared by all                85 kB
  ├ chunks/framework-xxxx.js                 45 kB
  ├ chunks/main-xxxx.js                      30 kB
  └ chunks/webpack-xxxx.js                   10 kB

pnpm add -D @next/bundle-analyzer

// next.config.js
const withBundleAnalyzer = require("@next/bundle-analyzer")({
  enabled: process.env.ANALYZE === "true",
});

module.exports = withBundleAnalyzer({});

ANALYZE=true pnpm build

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: [
      "lodash-es",
      "lucide-react",
      "@mui/material",
      "@radix-ui/react-icons",
    ],
  },
};

// 你写：
import { Button } from "@mui/material";

// Next.js 自动重写成：
import { Button } from "@mui/material/Button";

module.exports = {
  modularizeImports: {
    "date-fns": {
      transform: "date-fns/{{member}}",
    },
    lodash: {
      transform: "lodash/{{member}}",
    },
    "@my-org/icons": {
      transform: "@my-org/icons/dist/{{kebabCase member}}",
    },
  },
};

// 之前：editor 800kB 始终在首屏
import RichEditor from "@/components/RichEditor";

// 之后：用户点击才下载
import dynamic from "next/dynamic";
const RichEditor = dynamic(() => import("@/components/RichEditor"), {
  ssr: false,
  loading: () => <p>Loading editor...</p>,
});

export default function Page() {
  const [open, setOpen] = useState(false);
  return open ? (
    <RichEditor />
  ) : (
    <button onClick={() => setOpen(true)}>Edit</button>
  );
}

// ❌ 之前：Client 调用 lodash 处理数据
'use client'
import { groupBy } from 'lodash-es'

export function PostList({ posts }) {
  const grouped = groupBy(posts, 'category')
  return ...
}

// ✅ 之后：Server 处理，Client 只渲染
import { groupBy } from 'lodash-es'

export default async function PostList() {
  const posts = await db.posts.findMany()
  const grouped = groupBy(posts, 'category')
  return <PostsClient grouped={grouped} />
}

// PostsClient 不依赖 lodash，bundle 干净
'use client'
export function PostsClient({ grouped }) {
  return ...
}

import { Suspense } from "react";

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <SlowSection /> {/* 异步 fetch，慢 */}
      </Suspense>
      <Footer />
    </>
  );
}

// ❌ 串行：3 次 100ms = 300ms
const user = await db.users.find(id);
const posts = await db.posts.find({ userId: id });
const comments = await db.comments.find({ userId: id });

// ✅ 并行：max(100ms) = 100ms
const [user, posts, comments] = await Promise.all([
  db.users.find(id),
  db.posts.find({ userId: id }),
  db.comments.find({ userId: id }),
]);

import { cache } from "react";

export const getUser = cache(async (id: string) => {
  return db.users.find(id);
});

// 多个 Server Component 同时调，只查一次
// Layout.tsx
const user = await getUser(id);

// Page.tsx
const user = await getUser(id); // 命中 cache

// page.tsx
export const experimental_ppr = true;

export default function Page() {
  return (
    <>
      <StaticHeader />
      <Suspense fallback={null}>
        <DynamicCart /> {/* postpone 到运行时 */}
      </Suspense>
    </>
  );
}

async function getProducts() {
  "use cache";
  cacheTag("products");
  return db.products.findMany();
}

import Image from "next/image";

export default function Hero() {
  return (
    <Image
      src="/hero.jpg"
      alt="hero"
      width={1920}
      height={1080}
      priority // 关键：preload + fetchpriority="high"
      sizes="(max-width: 768px) 100vw, 1920px"
    />
  );
}

import { Inter } from "next/font/google";
const inter = Inter({
  subsets: ["latin"],
  display: "swap",
  adjustFontFallback: true, // 自动调系统字体 metrics，减小 CLS
});

export default function Layout({ children }) {
  return <html className={inter.className}>{children}</html>;
}

// next.config.js
module.exports = {
  images: {
    formats: ["image/avif", "image/webp"],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920],
    minimumCacheTTL: 60,
  },
};

"use client";
import { useState, useTransition, useDeferredValue } from "react";

export function SearchBox() {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);
  const [isPending, startTransition] = useTransition();

  const onChange = (e) => {
    setQuery(e.target.value); // 紧急：输入框立刻更新
    startTransition(() => {
      // 非紧急：搜索结果可被打断
      runHeavySearch(e.target.value);
    });
  };

  // 或对子组件 props 用 deferred value
  return (
    <>
      <input value={query} onChange={onChange} />
      <SearchResults query={deferredQuery} />
    </>
  );
}

import { useVirtualizer } from "@tanstack/react-virtual";

function BigList({ items }) {
  const parentRef = useRef(null);
  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 40,
  });

  return (
    <div ref={parentRef} style={{ height: 600, overflow: "auto" }}>
      <div style={{ height: virtualizer.getTotalSize() }}>
        {virtualizer.getVirtualItems().map((v) => (
          <div
            key={v.key}
            style={{ position: "absolute", top: v.start, height: v.size }}
          >
            {items[v.index].name}
          </div>
        ))}
      </div>
    </div>
  );
}

// ❌ 多次 setState 触发多次 re-render
useEffect(() => {
  setA(1);
  setB(2);
  setC(3);
}, []);

// ✅ React 18+ 自动 batch；但显式更清晰
useEffect(() => {
  setState({ a: 1, b: 2, c: 3 });
}, []);

module.exports = {
  experimental: {
    optimisticClientCache: true, // 默认就是 true
  },
};

// app/web-vitals.tsx
"use client";
import { useReportWebVitals } from "next/web-vitals";

export function WebVitalsReporter() {
  useReportWebVitals((metric) => {
    const body = JSON.stringify({
      ...metric,
      url: window.location.pathname,
      ua: navigator.userAgent,
    });

    // 用 sendBeacon 兼容页面卸载场景
    if (navigator.sendBeacon) {
      navigator.sendBeacon("/api/vitals", body);
    } else {
      fetch("/api/vitals", { body, method: "POST", keepalive: true });
    }
  });
  return null;
}

// app/layout.tsx
import { WebVitalsReporter } from "./web-vitals";

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <WebVitalsReporter />
        {children}
      </body>
    </html>
  );
}

// app/api/vitals/route.ts
export async function POST(req: Request) {
  const data = await req.json();
  // 写到 BI / Prometheus / Datadog
  logger.info(data, "web-vital");
  return new Response(null, { status: 204 });
}

{
  name: 'LCP',
  value: 2300,
  rating: 'needs-improvement',  // 'good' | 'needs-improvement' | 'poor'
  delta: 2300,
  id: 'v3-...',
  navigationType: 'navigate' | 'reload' | 'back-forward' | ...,
  attribution: { ... }  // 需启用 webVitalsAttribution
}

module.exports = {
  experimental: {
    webVitalsAttribution: ["LCP", "INP", "CLS"],
  },
};

# .github/workflows/lighthouse.yml
- name: Run Lighthouse CI
  uses: treosh/lighthouse-ci-action@v11
  with:
    urls: |
      https://preview-${{ env.PR_NUMBER }}.example.com/
      https://preview-${{ env.PR_NUMBER }}.example.com/products
    budgetPath: .lighthouserc.json

{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.85 }],
        "first-contentful-paint": ["error", { "maxNumericValue": 2000 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "interaction-to-next-paint": ["error", { "maxNumericValue": 200 }]
      }
    }
  }
}

cd learning/nextjs-40-lectures/fixtures/lecture-35
pnpm install && pnpm build && pnpm start