如何配置Next.js构建纯客户端静态SPA？无服务端无预渲染

下面是无需服务端支持、完全基于客户端实现的SPA搭建步骤与配置：

1. 初始化Next.js项目 #

推荐使用Pages Router（更适配纯客户端场景，规避App Router默认的服务端组件限制）：

npx create-next-app@latest client-only-spa --typescript --eslint --no-app --src-dir

执行命令时按提示选择：

• Would you like to use ESLint? Yes
• Would you like to use src/ directory? Yes
• Would you like to use App Router? No
• Would you like to customize the default import alias? No

若偏好App Router也可创建，但后续所有组件必须标记为客户端组件。

2. 核心配置修改（next.config.js） #

修改项目根目录的配置文件，确保生成纯静态输出并禁用所有服务端/预渲染特性：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 生成纯静态文件，无需Node.js服务支撑
  output: 'export',
  reactStrictMode: true,
  // 禁用Image组件的服务端优化（纯静态环境无法支持）
  images: {
    unoptimized: true,
  },
  // Pages Router下强制所有路由走客户端渲染
  experimental: {
    clientRouterFilter: false,
    clientRoutes: ['/**'],
  },
}

module.exports = nextConfig

3. 页面与组件配置 #

Pages Router 示例 #

所有页面直接编写客户端逻辑，无需添加服务端数据获取方法（如getStaticProps/getServerSideProps）：

src/pages/index.tsx：

import Link from 'next/link';
import { useEffect, useState } from 'react';

export default function Home() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    console.log('页面已在客户端加载');
  }, []);

  return (
    <div className="container">
      <h1>纯客户端SPA首页</h1>
      <p>计数：{count}</p>
      <button onClick={() => setCount(count + 1)}>增加</button>
      <Link href="/about">前往关于页面</Link>
    </div>
  );
}

src/pages/about.tsx：

import Link from 'next/link';

export default function About() {
  return (
    <div>
      <h1>关于页面</h1>
      <Link href="/">返回首页</Link>
    </div>
  );
}

App Router 示例（可选） #

若使用App Router，所有组件必须添加'use client'指令，强制转为客户端组件：

src/app/layout.tsx：

'use client';
import './globals.css';
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'Client-Only SPA',
  description: '纯客户端实现的Next.js SPA',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

src/app/page.tsx和src/app/about/page.tsx均需添加'use client'后编写客户端逻辑，与Pages Router示例类似。

4. 客户端数据与状态管理 #

所有数据获取、状态操作均需在客户端完成：

• 数据获取使用fetch结合useEffect，或客户端状态管理库（如SWR、React Query）
• 避免使用服务端数据获取方法，所有接口调用指向外部API，不要使用Next.js的/api路由（需服务端支撑）

客户端数据获取示例：

'use client';
import { useEffect, useState } from 'react';

export default function DataPage() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchData = async () => {
      try {
        const res = await fetch('https://api.example.com/public-data');
        const result = await res.json();
        setData(result);
      } catch (err) {
        console.error('数据获取失败:', err);
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, []);

  if (loading) return <div>加载中...</div>;
  return <div>{JSON.stringify(data)}</div>;
}

5. 打包与部署 #

1. 执行打包命令：

npm run build

项目根目录会生成out文件夹，包含所有静态HTML、CSS、JS文件。
2. 部署：直接将out目录上传至任意静态托管服务（如GitHub Pages、Netlify、Vercel静态托管模式），无需配置Node.js服务。

关键注意事项 #

• 环境变量：客户端可访问的环境变量需添加NEXT_PUBLIC_前缀，避免服务端专属变量泄漏
• 路由跳转：全部使用Next.js的Link组件，确保客户端导航（无页面刷新）
• 服务端API：不要使用Next.js的getServerSideProps、API Routes等依赖服务端的特性
• 资源处理：图片使用普通<img>标签，或配置images.unoptimized后使用Next.js Image组件

内容的提问来源于stack exchange，提问作者M Shaheer Haider