如何禁用Next.js 13 React服务器组件在构建阶段运行以避免连接错误

问题根源 #

Next.js 13 App Router的服务器组件（RSC）会在构建阶段执行静态渲染逻辑，如果你的组件在初始化时直接调用Prisma查询数据库，而GitHub Action构建环境里没有可访问的MySQL服务（更没法通过容器名db连接），自然会抛出连接错误。

具体解决方法 #

• 强制动态渲染，跳过构建阶段执行：
  在需要数据库查询的组件或页面文件顶部，添加export const dynamic = 'force-dynamic'，让Next.js只在用户请求时才执行该组件的逻辑，避免构建阶段触发数据库连接。示例代码：

  // app/page.tsx
  export const dynamic = 'force-dynamic';
  
  async function HomePage() {
    const data = await prisma.post.findMany();
    return <div>{JSON.stringify(data)}</div>;
  }
  
  export default HomePage;
  

  也可以用export const revalidate = 0达到同样效果，两者都是强制组件每次请求都重新执行。

• 构建阶段使用Mock Prisma客户端：
  创建一个带条件判断的Prisma客户端实例，在构建阶段返回模拟数据，不发起真实数据库连接。比如：

  // lib/prisma.ts
  import { PrismaClient } from '@prisma/client';
  
  let prisma: PrismaClient;
  
  // 检测是否处于构建阶段（通过环境变量判断）
  if (process.env.BUILD_STAGE === 'true') {
    // 返回Mock客户端，模拟查询逻辑
    prisma = {
      post: {
        findMany: async () => []
      }
    } as unknown as PrismaClient;
  } else {
    prisma = new PrismaClient();
  }
  
  export default prisma;
  

  然后在GitHub Action的构建步骤中，设置环境变量BUILD_STAGE=true，让构建过程自动切换到Mock模式。

• 用缓存和Fallback延迟数据获取：
  如果需要保留部分静态渲染能力，可以用unstable_cache缓存查询结果，同时开启dynamicParams让未预渲染的内容在请求时获取：

  // app/page.tsx
  import { unstable_cache } from 'next/cache';
  import prisma from '@/lib/prisma';
  
  const getPosts = unstable_cache(
    async () => await prisma.post.findMany(),
    ['posts-cache-key'],
    { revalidate: 3600 } // 缓存1小时
  );
  
  async function HomePage() {
    const data = await getPosts();
    return <div>{JSON.stringify(data)}</div>;
  }
  
  export const dynamicParams = true;
  export default HomePage;
  

内容的提问来源于stack exchange，提问作者Peter Kellner