什么是 ‘Zero-bundle-size Components’？在 RSC 中利用打包工具实现完全的服务端逻辑剔除

各位同学，大家好！

今天，我们齐聚一堂，将深入探讨前端工程领域一个令人兴奋且极具潜力的概念——“Zero-bundle-size Components”，即零打包体积组件。尤其是在React Server Components (RSC) 的语境下，如何利用现代打包工具的强大能力，实现对服务端逻辑的彻底剔除，从而为我们的客户端应用带来极致的性能表现，这将是本次讲座的核心议题。

1. 引言：前端性能的瓶颈与RSC的破局

在过去十年中，前端开发经历了飞速发展，单页应用（SPA）成为主流。然而，随着应用功能日益复杂，JavaScript 包的体积也水涨船高。用户在访问网站时，需要下载、解析、编译和执行大量的JavaScript代码，这直接导致了首次内容绘制（FCP）和首次有意义绘制（FMP）时间的增加，严重影响了用户体验，尤其是在网络条件不佳或设备性能有限的情况下。

我们尝试了各种优化手段：代码分割（Code Splitting）、Tree Shaking、按需加载、图片优化、CDN加速等等。这些方法固然有效，但它们大多是在“客户端渲染”这个基本范式下进行修修补补。客户端终究需要承担所有的渲染和交互逻辑，其性能上限是显而易见的。

正是在这样的背景下，React Server Components (RSC) 应运而生。RSC提出了一种革命性的范式转变：将组件的渲染工作从客户端转移到服务端。这意味着，在请求-响应周期中，部分组件可以在服务器上完成渲染，将最终的渲染结果（通常是序列化的JSX指令流）发送给客户端。客户端接收后，只需高效地将其转化为DOM，并进行必要的交互挂载。

RSC 的核心优势在于：

1. 减少客户端JavaScript包体积： 服务端组件的代码无需下载到客户端。
2. 更快的初始加载： 服务器直接生成HTML/JSX，客户端无需等待JavaScript加载和执行即可显示内容。
3. 更好的数据获取： 数据获取逻辑可以直接在服务端组件中进行，无需客户端-服务端多次往返。
4. 更强的安全性： 敏感逻辑和数据库查询等操作保留在服务端，不会暴露给客户端。

然而，RSC的潜力远不止于此。当我们谈论“Zero-bundle-size Components”时，我们追求的是一个更极致的目标：即使一个组件包含了复杂的服务器端逻辑，它在客户端打包产物中的体积也应该为零，或者仅包含一个微不足道的、用于触发服务器操作的桩（stub）。这需要我们的打包工具与RSC的运行时紧密协作，智能地识别并剔除那些永远不会在客户端执行的代码。

2. Zero-bundle-size Components 的定义与意义

什么是 Zero-bundle-size Component？

在RSC的语境下，“Zero-bundle-size Component”指的是一个组件或模块，其包含的所有服务端特定的逻辑和代码，在最终的客户端打包产物中被完全剔除，不占用任何字节。这意味着，即使该组件在服务器上执行了复杂的业务逻辑、数据库查询或文件系统操作，这些代码的实现细节也不会被发送到用户的浏览器。客户端可能只会收到该组件渲染的最终UI结构，或者一个轻量级的、用于与服务端进行异步通信的客户端桩函数。

其意义何在？

1. 极致的客户端性能： 零打包体积意味着更小的下载量、更快的解析和编译时间，从而实现更快的页面加载速度和更好的用户体验。
2. 更清晰的关注点分离： 开发者可以更明确地将业务逻辑区分为服务端逻辑和客户端交互逻辑，避免意外地将服务端代码引入客户端。
3. 安全性提升： 敏感的API密钥、数据库凭证或其他不应暴露给客户端的逻辑，可以安心地放置在服务端组件中，并确保它们不会被打包到客户端。
4. 减少维护负担： 避免了在客户端环境中模拟或兼容服务端API的复杂性。

要实现这一目标，我们不能仅仅依赖RSC运行时将服务器组件的JSX流发送给客户端。更重要的是，我们需要打包工具能够理解RSC的“客户端-服务端边界”，并根据这个边界来智能地构建两个独立的模块图：一个用于服务器，一个用于客户端。

3. RSC 中的客户端-服务端边界：'use client' 与 'use server'

在深入探讨打包工具之前，我们必须先理解RSC中划分客户端和服务器代码的基本机制：

3.1 'use client' 指令

当一个模块文件顶部声明了 'use client' 时，它及其所有导入的模块（除非这些导入又被其他 'use client' 边界明确地标记为客户端组件）都将被视为客户端组件。这意味着：

• 这些组件的代码将被打包并发送到客户端。
• 它们可以在浏览器中执行，访问浏览器API（如 window, document）。
• 它们可以包含交互逻辑、状态管理（useState, useReducer）、副作用（useEffect）等。
• 它们不能直接访问服务器端的API（如文件系统、数据库）。

示例：一个典型的客户端组件

// app/components/Counter.tsx
'use client'; // 明确标记为客户端组件

import React, { useState } from 'react';

interface CounterProps {
  initialCount?: number;
}

export default function Counter({ initialCount = 0 }: CounterProps) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
      <button onClick={() => setCount(c => c - 1)}>Decrement</button>
    </div>
  );
}

这个 Counter 组件需要 useState 钩子来管理状态，并且需要响应点击事件，因此它必须是一个客户端组件。它的代码会包含在客户端打包产物中。

3.2 默认的服务器组件

如果没有 'use client' 指令，一个组件默认就是服务器组件。这意味着：

• 它的代码只在服务器上执行。
• 它不能使用客户端特有的钩子（如 useState, useEffect）。
• 它可以直接访问服务器端的API（如文件系统、数据库、环境变量）。
• 它的代码不会被打包并发送到客户端。客户端只会收到其渲染的序列化JSX。

示例：一个简单的服务器组件

// app/page.tsx (这是一个默认的服务器组件)

// 假设我们有一个服务端工具函数
import { fetchProductData } from '../lib/server-data';

interface ProductPageProps {
  params: {
    productId: string;
  };
}

export default async function ProductPage({ params }: ProductPageProps) {
  const product = await fetchProductData(params.productId); // 直接在服务器端获取数据

  if (!product) {
    return <div>Product not found</div>;
  }

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <p>Price: ${product.price}</p>
      {/* 可以渲染客户端组件 */}
      {/* <AddToCartButton productId={product.id} /> */}
    </div>
  );
}

// lib/server-data.ts (这是一个服务器端工具函数)
import fs from 'fs/promises'; // 只能在服务器端使用

export async function fetchProductData(productId: string) {
  // 模拟从数据库或文件系统读取数据
  const data = await fs.readFile(`./data/products/${productId}.json`, 'utf-8');
  return JSON.parse(data);
}

在上述例子中，ProductPage 和 fetchProductData 都是服务器端代码。fs/promises 模块永远不会被打包到客户端。客户端只会收到 <h1>...</h1><p>...</p> 这样的HTML结构。

3.3 'use server' 指令 (Server Actions)

'use server' 是一个更特殊的指令，用于定义可以在客户端调用的服务器函数（Server Actions）。当一个函数或一个模块顶部声明了 'use server' 时，它表示该函数（或模块中的所有导出函数）是服务器端执行的，但可以通过网络从客户端调用。

• 模块级别： 如果放在模块顶部，该模块中的所有导出函数都将成为服务器 action。
• 函数级别： 如果放在函数内部，只有该函数是服务器 action。

示例：一个服务器 Action

// app/actions/cart.ts
'use server'; // 声明此模块中的函数为服务器 action

import { saveToDatabase } from '../lib/db'; // 这是一个服务器端数据库操作函数

export async function addToCart(productId: string, quantity: number) {
  console.log(`Adding product ${productId} with quantity ${quantity} to cart on server.`);
  // 执行服务器端逻辑，例如保存到数据库
  await saveToDatabase('cart', { productId, quantity });
  return { success: true, message: 'Item added to cart!' };
}

// lib/db.ts (服务器端数据库操作)
import mysql from 'mysql2/promise'; // 只能在服务器端使用

export async function saveToDatabase(collection: string, data: any) {
  const connection = await mysql.createConnection(process.env.DATABASE_URL!);
  // 模拟数据库插入操作
  await connection.execute(`INSERT INTO ${collection} SET ?`, [data]);
  await connection.end();
  console.log(`Saved ${JSON.stringify(data)} to ${collection}`);
}

// app/components/AddToCartButton.tsx
'use client'; // 这是一个客户端组件

import React from 'react';
import { addToCart } from '../actions/cart'; // 客户端导入服务器 action

interface AddToCartButtonProps {
  productId: string;
}

export default function AddToCartButton({ productId }: AddToCartButtonProps) {
  const handleAddToCart = async () => {
    // 客户端调用服务器 action
    const result = await addToCart(productId, 1);
    alert(result.message);
  };

  return (
    <button onClick={handleAddToCart}>
      Add to Cart
    </button>
  );
}

在这里，addToCart 函数的实际实现（包括 saveToDatabase 和 mysql 模块）只存在于服务器上。当客户端组件 AddToCartButton 导入 addToCart 时，打包工具不会将 addToCart 的完整实现代码打包到客户端。相反，它会生成一个轻量级的客户端桩（stub），这个桩负责：

1. 将 addToCart 的调用请求序列化。
2. 通过网络发送到服务器。
3. 接收服务器的响应并反序列化。

这个桩是实现零打包体积的关键，因为它允许客户端触发服务器逻辑，而无需加载服务器逻辑本身的任何代码。

4. 打包工具如何实现完全的服务端逻辑剔除

理解了客户端-服务器边界后，我们就可以探讨打包工具（如Webpack、Rollup、Vite及其在Next.js等框架中的定制化版本Turbopack）是如何利用这些信息来实现服务端逻辑的完全剔除的。

核心思想是：打包工具会为客户端和服务器构建两个独立的模块图（module graph）和打包产物。 在构建客户端打包产物时，所有明确标记为服务器端或仅在服务器端使用的代码都将被跳过或替换为客户端兼容的桩。

4.1 条件导入与 package.json 的 exports 字段

这是实现零打包体积组件的一个强大且标准化的机制，它利用了Node.js的条件导出（Conditional Exports）特性。通过在 package.json 的 exports 字段中定义不同的入口点，我们可以根据不同的环境（例如 react-server 环境 vs. 默认环境）提供不同的模块实现。

场景：一个工具库，既有服务器端实现，也有客户端实现（或客户端空实现）

假设我们有一个 utils 库，其中包含一个只在服务器端使用的 logToServer 函数，以及一个在客户端使用的 logToConsole 函数。或者更极致地，logToServer 在客户端直接被移除。

my-utils/package.json:

{
  "name": "my-utils",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "exports": {
    ".": {
      // 当在 React Server Components 环境中导入时
      "react-server": "./dist/server.js",
      // 默认情况下（例如在客户端或Node.js普通环境）导入时
      "default": "./dist/client.js"
    }
  },
  "types": "./dist/index.d.ts"
}

my-utils/src/server.ts:

// 这是一个只在服务器端运行的模块
import fs from 'fs/promises';

export function logToServer(message: string) {
  fs.appendFile('server.log', `${new Date().toISOString()} - ${message}n`);
  console.log(`[SERVER LOG]: ${message}`);
}

// 客户端不需要这个函数，或者在客户端版本中可以是一个空函数
export function logToConsole(message: string) {
  console.log(`[SERVER-SIDE CONSOLE LOG]: ${message}`);
}

my-utils/src/client.ts:

// 这是一个只在客户端运行的模块
// 注意：客户端无法访问 fs 模块
// export function logToServer(message: string) {
//   // 这里不能有服务器端代码，可以是一个空函数或者抛出错误
//   console.error("logToServer cannot be called on the client!");
// }

export function logToConsole(message: string) {
  console.log(`[CLIENT-SIDE CONSOLE LOG]: ${message}`);
}

// 为了类型兼容性，如果 `logToServer` 在 `server.ts` 中导出，
// 但在客户端不需要，可以这样处理：
export function logToServer(_message: string) {
  if (process.env.NODE_ENV !== 'production') {
    console.warn("Attempted to call logToServer on the client. This function should only be used on the server.");
  }
  // 生产环境下可以完全空实现，或者在打包时被 tree-shake 掉
}

my-app/app/layout.tsx (服务器组件):

// app/layout.tsx
import { logToServer, logToConsole } from 'my-utils'; // 导入 my-utils

export default function RootLayout({ children }: { children: React.ReactNode }) {
  logToServer('RootLayout rendered on server.'); // 在服务器端调用
  logToConsole('RootLayout rendered (server-side console).'); // 在服务器端调用

  return (
    <html lang="en">
      <body>
        {children}
      </body>
    </html>
  );
}

my-app/app/components/ClientComponent.tsx (客户端组件):

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

import React from 'react';
import { logToServer, logToConsole } from 'my-utils'; // 导入 my-utils

export default function ClientComponent() {
  React.useEffect(() => {
    // logToServer('ClientComponent mounted on client.'); // 尝试调用，但它在客户端是空函数或警告
    logToConsole('ClientComponent mounted (client-side console).'); // 在客户端调用
  }, []);

  return <div>Client Component loaded!</div>;
}

打包工具的行为：

1. 构建服务器打包产物时： 当打包工具（如Next.js的Turbopack）构建服务器端代码时，它会识别 react-server 条件，并解析 my-utils 为 ./dist/server.js。因此，logToServer 会包含 fs 模块的实际逻辑。
2. 构建客户端打包产物时： 当打包工具构建客户端代码时，它不会识别 react-server 条件，而是回退到 default 条件，解析 my-utils 为 ./dist/client.js。这样，logToServer 在客户端版本中只会是一个空函数（或带警告），而 fs 模块及其相关代码永远不会进入客户端打包。

通过这种方式，我们可以在同一个模块路径下提供完全不同的实现，从而实现服务端逻辑的彻底隔离。

4.2 server-only 包

React团队提供了一个名为 server-only 的特殊包，它是一个非常简洁但极其有效的工具，用于确保某个模块或代码块只在服务器端被导入和使用。

server-only 的工作原理：

这个包的核心代码非常简单，它包含一个 index.js 文件，其内容大致如下：

// server-only/index.js
// 这是一个在客户端环境下会抛出错误的模块

if (typeof window !== 'undefined') {
  // 这是一个运行时检查，确保它不会在浏览器环境中被导入
  throw new Error(
    'You are importing a component that needs "server-only". ' +
    'That only works in a Server Component but you have it in a Client Component. ' +
    'The "server-only" package is a marker to ensure that you don't accidentally do this.'
  );
}

当你在一个服务器端模块中导入 server-only 包时，没有任何副作用。但是，如果你在一个客户端模块中（即使是间接地）导入了任何一个直接或间接依赖 server-only 的模块，那么在客户端构建时，打包工具会识别到这个 server-only 导入，并在构建时抛出错误。

如何使用 server-only：

// app/lib/sensitive-data.ts (这个文件只应在服务器端使用)
import 'server-only'; // 声明此模块只应在服务器端使用

import { SECRET_API_KEY } from './env'; // 敏感信息

export async function fetchSensitiveData() {
  console.log('Fetching sensitive data with API key:', SECRET_API_KEY);
  // 模拟从外部服务获取数据
  return {
    data: 'Some very secret data',
    apiKeyUsed: SECRET_API_KEY,
  };
}

现在，任何服务器组件都可以安全地导入 app/lib/sensitive-data.ts。但是，如果一个客户端组件尝试导入 app/lib/sensitive-data.ts，或者导入了另一个依赖 app/lib/sensitive-data.ts 的模块，那么在打包阶段就会报错。

server-only 的优势：

• 强制性检查： 它提供了一种编译时（或更准确地说，是打包时）的检查，防止开发者无意中将服务器端代码泄露到客户端。
• 语义清晰： 明确地标记了哪些文件是服务器端专属的，提升了代码的可读性和可维护性。
• 零运行时开销： 在服务器端，它几乎是零开销。在客户端，它直接阻止了不正确的导入，因此也不会有额外的运行时代码。

这在实践中是非常重要的，因为它不仅仅是优化打包体积，更是强制了代码的安全性和架构的纯洁性。

4.3 打包工具的 Tree Shaking 与死代码消除

现代打包工具都具备强大的 Tree Shaking (摇树优化) 能力，即通过静态分析，移除那些在最终代码中从未被使用的代码。在RSC的上下文中，Tree Shaking 扮演着至关重要的角色。

打包流程示意图：

阶段	客户端打包过程	服务器打包过程
模块图构建	从根客户端组件（如 page.tsx 中导入的 'use client' 组件）开始，追踪所有 import 依赖。	从根服务器组件（如 page.tsx 自身）开始，追踪所有 import 依赖。
边界识别	遇到 'use server' 模块/函数时，将其替换为网络桩。遇到 'use client' 模块时，将其代码加入客户端图。	遇到 'use client' 模块时，将其视为渲染的 JSX 引用，不将其代码加入服务器图。遇到 'use server' 模块时，将其代码加入服务器图。
条件导出解析	解析 package.json 的 exports 字段时，优先匹配 default 条件。	解析 package.json 的 exports 字段时，优先匹配 react-server 条件。
死代码消除 (Tree Shaking)	移除客户端模块图中未被引用或仅在服务器端使用的代码路径。	移除服务器模块图中未被引用或仅在客户端使用的代码路径。
产物生成	生成浏览器可执行的 JavaScript、CSS 等资源。	生成服务器上可执行的 JavaScript 代码（用于RSC渲染和Server Actions执行）。

示例：如何通过 Tree Shaking 剔除服务端函数

考虑一个共享文件 shared-lib.ts：

// shared-lib.ts
export function clientOnlyFunction() {
  console.log('This runs on the client.');
  return 'client data';
}

export function serverOnlyFunction() {
  // 假设这里有 fs.readFile 等服务器端特有代码
  console.log('This runs on the server.');
  // fs.readFileSync('./config.json', 'utf-8');
  return 'server data';
}

export function sharedFunction() {
  console.log('This can run on both client and server.');
  return 'shared data';
}

1. 服务器组件导入：

   // app/server-page.tsx (服务器组件)
   import { serverOnlyFunction, sharedFunction } from '../shared-lib';
   
   export default async function ServerPage() {
     const serverData = serverOnlyFunction();
     const commonData = sharedFunction();
     return (
       <div>
         <p>Server Data: {serverData}</p>
         <p>Common Data: {commonData}</p>
       </div>
     );
   }

   在构建服务器打包产物时，clientOnlyFunction 因为没有被 ServerPage 导入，会被 Tree Shaking 掉。serverOnlyFunction 和 sharedFunction 的代码会被包含。

2. 客户端组件导入：

   // app/client-component.tsx
   'use client';
   import React from 'react';
   import { clientOnlyFunction, sharedFunction } from '../shared-lib';
   
   export default function ClientComponent() {
     React.useEffect(() => {
       const clientData = clientOnlyFunction();
       const commonData = sharedFunction();
       console.log(`Client Data: ${clientData}, Common Data: ${commonData}`);
     }, []);
     return <div>Hello from Client!</div>;
   }

   在构建客户端打包产物时，serverOnlyFunction 因为没有被 ClientComponent 导入，会被 Tree Shaking 掉。clientOnlyFunction 和 sharedFunction 的代码会被包含。

这种智能的分析和剔除机制是实现“Zero-bundle-size Components”的基础。打包工具不仅仅是简单地将文件复制到产物中，而是会深入分析模块间的依赖关系，并根据客户端或服务器的执行环境，精确地决定哪些代码是必要的。

4.4 Next.js 等框架的定制化打包器

像Next.js这样的框架，在底层对打包工具（早期是Webpack，现在是定制的Turbopack）进行了深度集成和优化，以无缝支持RSC。它们在打包流程中增加了额外的转换层：

1. 识别边界： 打包器会扫描所有文件，识别 'use client', 'use server' 指令。
2. 模块重写：
   • 对于服务器组件导入的客户端组件，打包器会将其转换为一个特殊的引用，指示客户端在 hydration 时加载该组件。
   • 对于客户端组件导入的服务器 action，打包器会生成一个网络桩函数来替换原始的服务器 action 实现。
   • 对于客户端组件导入的服务器专用模块（如含有 fs 或 server-only 的模块），打包器会确保这些模块不会被包含在客户端打包中，甚至在开发阶段抛出错误。
3. HMR (Hot Module Replacement) 兼容： 在开发模式下，打包器还需要确保 HMR 在客户端和服务器端都能正确工作，但又不能因此泄露服务器代码到客户端。

这种深度的集成使得开发者可以以一种声明式的方式编写组件，而无需手动管理客户端和服务器端的打包逻辑。框架的打包器会处理所有的复杂性。

5. 实践中的零打包体积组件：代码与案例分析

现在，让我们通过更具体的代码示例来展示如何在实际项目中实现零打包体积组件。

项目结构假设：

my-rsc-app/
├── app/
│   ├── page.tsx             # 根服务器组件
│   ├── layout.tsx           # 根服务器布局
│   ├── components/
│   │   ├── ServerMessage.tsx  # 纯服务器组件
│   │   ├── ClientButton.tsx   # 纯客户端组件
│   │   └── SharedDisplay.tsx  # 混合组件或共享逻辑
│   ├── api/
│   │   └── route.ts         # Next.js API 路由 (独立于RSC)
│   └── actions/
│       └── formActions.ts   # Server Actions 模块
├── lib/
│   ├── db.ts                # 服务器端数据库操作
│   ├── utils.ts             # 共享工具函数
│   └── secure-config.ts     # 包含敏感信息的服务器端配置
├── package.json
└── tsconfig.json

5.1 纯服务器组件及其依赖

lib/db.ts (服务器端数据库操作):

// lib/db.ts
// 这是一个纯服务器端模块，不应包含在客户端包中
import 'server-only'; // 确保这个文件永远不会被客户端导入

import { Pool } from 'pg'; // 假设使用 PostgreSQL 客户端库

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

export async function getPostsFromDB() {
  const client = await pool.connect();
  try {
    const res = await client.query('SELECT id, title, content FROM posts ORDER BY created_at DESC');
    return res.rows;
  } finally {
    client.release();
  }
}

export async function createPostInDB(title: string, content: string) {
  const client = await pool.connect();
  try {
    await client.query('INSERT INTO posts (title, content) VALUES ($1, $2)', [title, content]);
    return true;
  } finally {
    client.release();
  }
}

客户端打包： pg 库和 lib/db.ts 的所有代码，因为有 server-only 标记，并且只被服务器组件导入，绝对不会进入客户端打包。

app/components/ServerMessage.tsx (纯服务器组件):

// app/components/ServerMessage.tsx
import { getPostsFromDB } from '../../lib/db'; // 导入服务器端数据库操作

export default async function ServerMessage() {
  const posts = await getPostsFromDB(); // 直接在服务器端获取数据

  return (
    <div className="server-message">
      <h2>Server-Rendered Posts</h2>
      {posts.length === 0 ? (
        <p>No posts found.</p>
      ) : (
        <ul>
          {posts.map(post => (
            <li key={post.id}>
              <h3>{post.title}</h3>
              <p>{post.content}</p>
            </li>
          ))}
        </ul>
      )}
      <p>This component's logic runs entirely on the server.</p>
    </div>
  );
}

客户端打包： ServerMessage.tsx 的代码本身，包括对 getPostsFromDB 的调用，不会被打包到客户端。客户端只会收到其渲染后的 JSX 结构（即 div, h2, ul, li 等 HTML 元素及其内容）。

5.2 客户端组件与服务器 Action

app/actions/formActions.ts (服务器 Action):

// app/actions/formActions.ts
'use server'; // 声明此模块中的函数为服务器 action

import { createPostInDB } from '../../lib/db'; // 导入服务器端数据库操作

export async function submitPost(formData: FormData) {
  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  if (!title || !content) {
    return { success: false, message: 'Title and content are required.' };
  }

  try {
    await createPostInDB(title, content);
    console.log(`New post "${title}" created successfully.`);
    return { success: true, message: 'Post created!' };
  } catch (error) {
    console.error('Failed to create post:', error);
    return { success: false, message: 'Failed to create post.' };
  }
}

客户端打包： submitPost 函数的实现（包括 createPostInDB 和 pg 库）不会进入客户端打包。客户端只会得到一个轻量级的桩函数。

app/components/PostForm.tsx (客户端组件):

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

import React, { useState } from 'react';
import { submitPost } from '../actions/formActions'; // 导入服务器 action

export default function PostForm() {
  const [status, setStatus] = useState('');

  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    setStatus('Submitting...');
    const formData = new FormData(event.currentTarget);
    const result = await submitPost(formData); // 客户端调用服务器 action
    setStatus(result.message);
    if (result.success) {
      event.currentTarget.reset(); // 清空表单
    }
  };

  return (
    <div className="post-form">
      <h3>Create New Post</h3>
      <form onSubmit={handleSubmit}>
        <div>
          <label htmlFor="title">Title:</label>
          <input type="text" id="title" name="title" required />
        </div>
        <div>
          <label htmlFor="content">Content:</label>
          <textarea id="content" name="content" rows={5} required></textarea>
        </div>
        <button type="submit">Submit Post</button>
        {status && <p>{status}</p>}
      </form>
    </div>
  );
}

客户端打包： PostForm.tsx 的代码会进入客户端打包，因为它需要管理状态和处理交互。但它导入的 submitPost 只是一个桩，其背后的服务器逻辑不会被打包。

5.3 根服务器组件整合

app/page.tsx (根服务器组件):

// app/page.tsx
import ServerMessage from './components/ServerMessage';
import PostForm from './components/PostForm';

export default function HomePage() {
  return (
    <main style={{ maxWidth: '800px', margin: '0 auto', padding: '20px' }}>
      <h1>Welcome to My RSC App</h1>
      <ServerMessage /> {/* 服务器组件，其逻辑不进客户端包 */}
      <hr />
      <PostForm />      {/* 客户端组件，但其 Server Action 逻辑不进客户端包 */}
    </main>
  );
}

在这个根组件中，ServerMessage 的服务端数据获取逻辑不会到达客户端，PostForm 的提交逻辑也不会到达客户端。客户端最终的打包产物中，只包含 PostForm 自身的 React 状态管理和事件处理代码，以及必要的 React 运行时。

5.4 共享工具函数的条件导出

假设我们有一个工具函数，在服务器端需要访问环境变量，而在客户端不需要。

lib/utils.ts:

// lib/utils.ts
// 默认（客户端）版本
export function getGreeting() {
  return "Hello from client!";
}

// 模拟一个服务器端特有的函数
export function getServerConfigValue(key: string) {
  // 在客户端，这个函数要么不存在，要么是空函数
  return `[Client Placeholder for ${key}]`;
}

为了实现条件导出，我们可以在 lib 目录下为 utils.ts 创建一个 package.json：

my-rsc-app/lib/package.json:

{
  "name": "my-app-lib",
  "version": "1.0.0",
  "private": true,
  "exports": {
    "./utils": {
      "react-server": "./utils.server.ts",
      "default": "./utils.ts"
    },
    // 可以有其他导出
    "./db": "./db.ts",
    "./secure-config": "./secure-config.ts"
  }
}

my-rsc-app/lib/utils.server.ts:

// lib/utils.server.ts (服务器版本)
// 注意：这个文件只会在服务器环境中被导入
export function getGreeting() {
  return "Hello from server!";
}

export function getServerConfigValue(key: string) {
  // 在服务器端，可以安全地访问环境变量
  return process.env[key] || `Config value for ${key} not found on server.`;
}

现在，当服务器组件导入 my-app-lib/utils 时，会得到 lib/utils.server.ts 的实现；而客户端组件导入 my-app-lib/utils 时，会得到 lib/utils.ts 的实现。这样，process.env 的使用及其相关逻辑永远不会出现在客户端打包中。

6. 高级场景与注意事项

6.1 序列化限制

服务器组件和客户端组件之间传递数据时，数据必须是可序列化的。这意味着你不能直接传递函数、类实例、Symbol、Set、Map等非基本类型数据作为 props。Server Actions 的参数和返回值也有同样的限制。

• 可行： JSON可序列化的数据（字符串、数字、布尔值、数组、对象字面量）。
• 不可行： 函数、日期对象（需要手动序列化为字符串）、正则、Promise、Set、Map、DOM元素、FormData对象等。

对于 FormData，Server Actions 是一个例外，因为它们被设计为可以直接接收 FormData 对象，由框架在底层进行特殊处理。

6.2 渲染层次与嵌套

• 服务器组件可以导入并渲染客户端组件： 客户端组件的打包代码会包含在客户端包中。
• 客户端组件不能直接导入并渲染服务器组件： 如果客户端组件需要渲染服务器组件生成的内容，它必须通过将其作为 children prop 接收，或者通过其他方式由父级服务器组件提供。

// app/page.tsx (服务器组件)
import ClientComponent from './components/ClientComponent';
import ServerOnlyComponent from './components/ServerOnlyComponent';

export default function MyPage() {
  return (
    <div>
      <ServerOnlyComponent /> {/* 服务器组件渲染服务器组件 */}
      <ClientComponent>
        <ServerOnlyComponent /> {/* 错误：客户端组件不能渲染服务器组件作为其子组件 */}
        {/* 正确的做法是将ServerOnlyComponent作为prop传递给ClientComponent，
            但ClientComponent不能直接导入ServerOnlyComponent */}
      </ClientComponent>
      {/* 更好的做法是： */}
      <ClientComponent serverContent={<ServerOnlyComponent />} />
    </div>
  );
}

// app/components/ClientComponent.tsx
'use client';
export default function ClientComponent({ children, serverContent }: { children?: React.ReactNode, serverContent?: React.ReactNode }) {
  return (
    <div>
      <h2>Client Component</h2>
      {children}
      {serverContent} {/* 接收由服务器组件渲染的JSX */}
    </div>
  );
}

通过 serverContent prop 传递，ClientComponent 只是接收并渲染已经由服务器组件序列化好的 JSX 片段，它本身并不需要知道 ServerOnlyComponent 的代码。

6.3 动态导入 (Dynamic Imports)

动态导入 (import()) 同样可以与 RSC 结合使用，进一步优化客户端包体积。

• 客户端组件中的动态导入： 可以实现客户端组件的按需加载，例如，仅当用户点击某个按钮时才加载一个大型图表库。
• 服务器组件中的动态导入： 可以在服务器端按需加载模块，但这更多是关于服务器端资源优化的，与客户端包体积关系不大。

在客户端组件中使用动态导入时，打包工具会为动态导入的模块创建单独的 chunk，从而实现更细粒度的代码分割。

6.4 环境变量

• 服务器组件： 可以直接访问 process.env 中的所有环境变量。
• 客户端组件： 只能访问那些以 NEXT_PUBLIC_ (在Next.js中) 或其他框架约定前缀开头的环境变量。这是为了防止敏感信息泄露到客户端。

打包工具在构建客户端包时，会将这些公共环境变量值替换为硬编码的字符串，而其他非公共的环境变量则会被移除。

7. Zero-bundle-size Components 的最佳实践

要充分利用零打包体积组件的优势，并避免常见的陷阱，请遵循以下最佳实践：

1. 默认使用服务器组件： 除非有明确的交互需求，否则应将组件视为服务器组件。这有助于自然地将逻辑保留在服务器端。
2. 严格划分客户端-服务器代码：
   • 将所有需要浏览器API（window, document）或React Hooks（useState, useEffect）的组件标记为 'use client'。
   • 将所有需要访问文件系统、数据库、API密钥或敏感逻辑的模块或函数保留在服务器端，并考虑使用 server-only 包进行强制检查。
   • 对于 Server Actions，确保其实现细节（包括所有依赖）只存在于服务器端。
3. 善用 server-only 包： 对于任何不希望在客户端打包中出现的模块，即使它目前只被服务器组件导入，也加上 import 'server-only';。这提供了一个强大的编译时保障。
4. 利用条件导出： 对于那些在客户端和服务器端需要不同实现的共享模块，使用 package.json 的 exports 字段和 react-server 条件。
5. 警惕间接依赖： 即使一个文件本身没有 'use client'，如果它被一个 'use client' 组件间接导入，那么它的代码也会被视为客户端代码。仔细审查依赖链，确保服务器端专属逻辑不会被意外地带入客户端。
6. 优化数据传输： 确保从服务器传递到客户端的 props 都是可序列化的，并且尽可能精简，只包含客户端渲染所需的数据。
7. 性能分析： 定期使用打包分析工具（如Webpack Bundle Analyzer）检查客户端打包产物，确保没有意外的服务器端代码混入。
8. 理解 Server Actions 的桩： 客户端调用 Server Actions 只是发送一个网络请求，其代码体积微乎其微。这是一种非常高效的客户端-服务器通信方式。

8. 展望未来

零打包体积组件的概念和RSC的技术栈仍在快速发展。我们可以预见以下趋势：

• 更智能的打包工具： 未来的打包工具将具备更强大的静态分析能力，能够更精准地识别并剔除死代码，甚至在没有明确指令的情况下，也能根据代码的上下文判断其执行环境。
• 更完善的框架支持： 更多前端框架可能会借鉴RSC的思想，引入类似的客户端-服务器边界划分机制。
• 标准化的条件导出： react-server 等条件可能会成为更广泛的行业标准，使得跨框架的零打包体积组件开发更加统一。
• 开发者体验的提升： 随着工具链的成熟，开发者将能够以更直观的方式编写全栈组件，而不必过多关注底层的打包和部署细节。

9. 结语

零打包体积组件代表了前端性能优化的一个新纪元。通过React Server Components和现代打包工具的紧密协作，我们能够将大量计算和逻辑从客户端转移到服务器，从而大幅削减客户端JavaScript包的体积，带来前所未有的加载速度和响应能力。掌握这些技术，不仅能帮助我们构建更高效、更安全的Web应用，也为我们重新思考前端架构、实现真正的全栈开发提供了强大的思想武器。这是一个激动人心的时代，让我们共同探索和实践，为用户带来更极致的Web体验！