Next.js App Router预渲染错误：Supabase Auth构建/dashboard时self未定义

问题详情 #

使用Next.js 15.3.5搭配App Router和Supabase Auth Helpers，执行npm run build时，/dashboard页面预渲染报错，错误信息如下：

Next.js 15.3.5
…
Compiled successfully in 19.0s
Linting and checking validity of types
Collecting page data
Error occurred prerendering page "/dashboard". Read more: https://nextjs.org/docs/messages/prerender-error
ReferenceError: self is not defined
at 56092 (.next/server/chunks/92.js:1:347910)
at t (.next/server/webpack-runtime.js:1:128)
at 68222 (.next/server/app/dashboard/page.js:1:7889)
…
Export encountered an error on /dashboard/page: /dashboard, exiting the build.

当前app/dashboard/page.tsx代码：

import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { useEffect, useState } from 'react';

export default function DashboardPage() {
  const supabase = createClientComponentClient({ cookies });
  const [letters, setLetters] = useState<any[]>([]);

  useEffect(() => {
    // fetch some data client-side
    supabase.from('letters').select('*').then(({ data }) => {
      setLetters(data || []);
    });
  }, [supabase]);

  return (
    <div>
      <h1>Dashboard</h1>
      <p>You have ...</p>
    </div>
  );
}

已尝试但无效的方法：

• 在use client后添加export const dynamic = 'force-dynamic';
• 在next.config.js中禁用outputFileTracing

解决方案 #

核心问题是组件未正确声明为客户端组件，且createClientComponentClient使用方式错误，按以下步骤修改：

1. 在文件最顶部添加"use client";指令：确保组件在客户端运行，避免服务器预渲染时访问浏览器全局对象self
2. 移除cookies参数：createClientComponentClient在客户端环境下会自动读取浏览器中的认证信息，不需要传入服务器端的cookies() API

修改后的完整代码：

"use client"; // 必须放在文件第一行

import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { useEffect, useState } from 'react';

export default function DashboardPage() {
  const supabase = createClientComponentClient();
  const [letters, setLetters] = useState<any[]>([]);

  useEffect(() => {
    const fetchLetters = async () => {
      const { data } = await supabase.from('letters').select('*');
      setLetters(data || []);
    };

    fetchLetters();
  }, [supabase]);

  return (
    <div>
      <h1>Dashboard</h1>
      <p>You have {letters.length} letters</p>
    </div>
  );
}

额外说明 #

• createClientComponentClient是专为客户端组件设计的工具，只有标记use client后，Next.js才会在客户端执行它的逻辑，避免服务器端预渲染报错
• 如果需要在服务器端获取Supabase数据，应使用createServerComponentClient（无需use client，但要传入cookies()），但你的场景是客户端拉取数据，所以用客户端版本即可
• 无需额外设置dynamic = 'force-dynamic'，正确标记use client后，Next.js会自动跳过该页面的静态预渲染

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