nextjs实践

shadcn和tailwindcss一起使用，shadcn组件的样式丢失

其实这个问题我2025-09月份就遇到了，但直到现在2026-01才想到要解决。

原因1：tailwind.config.js 的 content 路径没包含 shadcn 组件目录

安装了二者之后，tailwind.config.js里面不会自动包含shadcn的组件目录，所以需要自己添加：


x
1
// tailwind.config.js / tailwind.config.ts
2
3
module.exports = {
4
  content: [
5
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
6
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
7
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
8
    
9
    // 必须包含你放 shadcn 组件的路径！
10
    "./src/components/ui/**/*.{js,ts,jsx,tsx}",
11
  ],
12
  // ...其他配置
13
}

原因2：确认全局样式文件被正确引入（通常在根布局）


xxxxxxxxxx
11
1
// app/layout.tsx 或 app/layout.js（Next.js App Router）
2
3
import './globals.css'           // ← 这一行一定要有
4
5
export default function RootLayout({ children }) {
6
  return (
7
    <html lang="zh-CN">
8
      <body>{children}</body>
9
    </html>
10
  )
11
}

早就该解决了。

配置prisma和postgresql

参考：https://www.prisma.io/docs/getting-started/prisma-orm/quickstart/postgresql

1、安装依赖


xxxxxxxxxx
2
1
npm install prisma @types/node @types/pg --save-dev 
2
npm install @prisma/client @prisma/adapter-pg pg dotenv

2、初始化prisma orm


xxxxxxxxxx
1
1
npx prisma init --datasource-provider postgresql --output ../generated/prisma

3、编辑.env文件，添加数据库地址

我使用的是neon，它提供5G的存储空间，够用了。使用的是google账号登录的。

每一个新项目最好创建一个新数据库，因为prisma操作会同步数据库，如果使用现有的数据库，会造成冲突。那么就点击create database，会创建一个新数据库。

将这个地址粘贴到.env文件里面即可。

4、在prisma/schema.prisma文件里面，定义data model

5、创建和应用迁移

只要model变更了，就执行这两个命令：


xxxxxxxxxx
2
1
npx prisma migrate dev --name init
2
npx prisma generate

6、初始化prisma client

创建lib/prisma.ts


xxxxxxxxxx
10
1
import "dotenv/config";
2
import { PrismaPg } from '@prisma/adapter-pg'
3
import { PrismaClient } from '../generated/prisma/client'
4
5
const connectionString = `${process.env.DATABASE_URL}`
6
7
const adapter = new PrismaPg({ connectionString })
8
const prisma = new PrismaClient({ adapter })
9
10
export { prisma }

7、接下来就可以在lib文件夹里面写相关的数据库操作代码了，先引入定义好的prismaClient，然后正常写代码。

8、添加模拟数据

注意：
postgresql里面的字段名要采用下划线的形式，不要采用小驼峰的形式，下划线是SQL规范。在prisma里面定义的时候也要注意。
但是这样做之后，在组件代码里面使用字段名有不方便了，JS里面使用下划线比较少见，更多的是小驼峰的形式，这该怎么办呢？

prisma有两个方法来帮助我们，@@map()方法和@map()方法，在定义表的时候，在表的最后面加上表的复数形式@@map("comments")，这样prisma在postgresql创建表的时候，就会自动将数据表的名称变为comments，而不是大驼峰的形式。
https://www.prisma.io/docs/orm/prisma-schema/data-model/models#defining-models
✅ @@map ——模型映射（Model/Table Mapping）
作用：指定 Prisma model 对应数据库中的表名。
如果 Prisma 模型名是大驼峰（默认是），但你希望数据库用复数表名或蛇形命名，则使用 @@map.
简单来讲，@@map()里面的参数就是定义model名称的复数形式，你指定是什么就是什么，如果不知道英文单词的复数，就搜索一下即可。

✅ @map ——字段映射（Field Mapping）
作用：指定 Prisma 字段对应数据库中的实际列名。
默认情况下 Prisma 会直接使用字段名作为数据库列名。如果你使用了小驼峰、想让数据库是下划线，就要用 @map。比如说createdAt，用的时候是这样用，但是在定义的时候，postgresql里面需要定义为下划线的形式，就需要这样指定：createdAt DateTime @default(now()) @map("created_at")。
下面是一个model样板。
xxxxxxxxxx
15
1
model User {
2
id        String    @id @default(cuid())
3
email     String    @unique
4
name      String?
5
image     String?
6
role      String    @default("USER") // USER / ADMIN
7
createdAt DateTime  @default(now()) @map("created_at")
8
updatedAt DateTime  @updatedAt @map("updated_at")
9
10
articles  Article[]
11
comments  Comment[]
12
photos    Photo[]
13
14
@@map("users")
15
}

使用https://mockaroo.com/来创建模拟数据。

需要注意的是datetime，要选择SQL datetime这种类型，否则格式不对。

这里就是SQL的插入语句，复制

在编辑器中修改表名，粘贴到neno SQL Editor里面执行即可。这种方法我试过了，太复杂了，所以还是使用本地编辑器导入csv文件来做吧。

neon的链接地址：


xxxxxxxxxx
1
1
DATABASE_URL='postgresql://neondb_owner:npg_PdcV96hSGZFR@ep-misty-meadow-a8g8kxvi-pooler.eastus2.azure.neon.tech/neondb?sslmode=require&channel_binding=require'

➤ Host（服务器地址）


xxxxxxxxxx
1
1
ep-msty-meadow-a8g8kxvi-pooler.eastus2.azure.neon.tech

➤ Port

Neon 默认 PostgreSQL 端口是：


xxxxxxxxxx
1
1
5432

➤ Database


xxxxxxxxxx
1
1
neondb

➤ Username


xxxxxxxxxx
1
1
neondb_owner

➤ Password


xxxxxxxxxx
1
1
PdcV96hSGZFR

粘贴进去即可连接。然后导入数据。

注意：

Prisma 遵循 camelCase (驼峰命名法) 定义模型字段，但大多数传统的 PostgreSQL 数据库默认使用 snake_case (下划线命名法) 作为物理列名。所以我在添加数据的时候，如果是这样的语句，会报错createat column does not exist：


xxxxxxxxxx
1
1
insert into public."Product" (id, name, description, price, image, stock, sales, category, createAt, updateAt) values (1, 'Portable Solar Generator', 'Eco-friendly generator for outdoor adventures.', 399.99, 'http://dummyimage.com/185x100.png/5fa2dd/ffffff', '67989', '3837', 'Outdoor', '2025-03-12 15:38:53', '2025-07-14 17:13:57');

所以需要改为这样craete_at，update_at，也就是说凡是有小驼峰命名的地方，都要改为下划线命名：


xxxxxxxxxx
1
1
insert into public."Product" (id, name, description, price, image, stock, sales, category, create_at, update_at) values (1, 'Portable Solar Generator', 'Eco-friendly generator for outdoor adventures.', 399.99, 'http://dummyimage.com/185x100.png/5fa2dd/ffffff', '67989', '3837', 'Outdoor', '2025-03-12 15:38:53', '2025-07-14 17:13:57');

dbeaver连接neon保持不掉线

原因

✅ 原因 1：Neon Serverless 会自动断开空闲连接

Neon 是 serverless Postgres，为了节省资源，它会自动关闭长时间空闲的连接。

默认情况（Neon 免费 tier）：

行为	Neon 的做法
连接 5 分钟无活动	会自动关闭连接
空闲到达阈值	会 suspend compute（自动休眠）
再次连接	需要唤醒 → 所以你看到“重新连接”提示

这就是为什么 DBeaver 停在那里不动一会儿之后，连接突然失效。

✅ 原因 2：你使用的是 Neon 的 \pooler\ 端点

你现在的连接串是这样的：


xxxxxxxxxx
1
1
...-pooler.eastus2.azure.neon.tech

Neon 的 Pooler 也有自己的超时机制：

机制	描述
`pooler_idle_timeout`	连接一段时间不活跃会被关闭
`pooler_max_client_conn`	超过总连接数会丢弃/挤掉连接

➡ 所以 DBeaver 会被踢掉是完全正常的。

✅ 原因 3：DBeaver 默认不会自动保持心跳

DBeaver 对 PostgreSQL 不会默认发心跳包（KeepAlive）。

因此：

Neon 超时策略 +
DBeaver 不保持活跃

= 连接被断开，必须重新连接。

解决办法

nextjs配置访问外部图片白名单

nextjs的Image组件，不能直接访问外部图片链接，需要在next.config.ts里面进行配置：

列表页，添加搜索、分页功能

NuQS 的核心就是 URL query state 管理器，分 Server 端和 Client 端使用场景：

Server Components / Route Handler
- 使用 nuqs/server
- 读取 query params → 页面渲染一次
- Server Component 会根据 query 改变重新渲染（页面 SSR）
Client Components
- 使用 useQueryState + nuqs（注意不是 nuqs/server）
- 修改 query state 会触发组件重新渲染，但不会自动刷新整个页面
- React Query / useEffect / table hook 可以监听变化，然后发请求刷新数据

可以知道，通过nuqs改变url之后，server components能够重新渲染一次。

使用server components来实现

使用nuqs修改url之后，server components不能自动重新渲染。比如说/users改为/users?page=2，是触发不了重新渲染的。所以使用nuqs来实现是有问题的，最起码现在是不行的。可以看C:\git\github\shangguigu-learn\Codevolution\NextJS\nextjs实践\list-search-pagination\src\app\simpleTest\page.tsx这个例子。

但还是可以实现，采用Link来翻页，使用nuqs来搜索，直接使用fetch来请求数据，通过searchParams来接收参数，这样nextjs的适配性是最好的。更进一步的，如果想让接口在服务端运行，可以加上server action，在页面初始化、翻页、搜索时调用这个接口即可。案例代码：C:\git\github\shangguigu-learn\Codevolution\NextJS\nextjs实践\list-search-pagination\src\app\actionExample\page.tsx

可以看到，用到了server components的快速，也能够进行交互。把交互放到别的组件即可。


xxxxxxxxxx
32
1
// app/posts/page.tsx
2
import { fetchPostsAction } from "./actions";
3
import PostsTableClient from "./components/PostsTableClient";
4
import { Suspense } from "react";
5
6
export default async function ActionPostsPage({
7
  searchParams,
8
}: {
9
  searchParams: Promise<Record<string, string | string[] | undefined>>;
10
}) {
11
  const data = await searchParams;
12
  const page = Number(data.page) || 1;
13
  const perPage = Number(data.perPage) || 10;
14
  const search = typeof data.search === "string" ? data.search : "";
15
16
  const initialData = await fetchPostsAction({ page, perPage, search });
17
18
  return (
19
    <div className="container mx-auto py-10">
20
      <h1 className="text-3xl font-bold mb-6">帖子管理</h1>
21
22
      <Suspense fallback={<div>初始加载中...</div>}>
23
        <PostsTableClient
24
          initialPosts={initialData.posts}
25
          initialTotal={initialData.total}
26
          initialPages={initialData.pages}
27
          initialPage={page}
28
        />
29
      </Suspense>
30
    </div>
31
  );
32
}

有一个问题：我写了server action，这个接口为什么能够在客户端看到呢？

原因：nuqs+server action，'server action'的函数体永远不在客户端，之所以客户端能够看到请求了接口，其实是浏览器触发的，所以能看到。

听说还可以使用react query+nuqs+server action来处理，到时候看吧。

注意：
有一些案例中采用<form>来搜索，form提交之后确实能触发页面更新，但是form触发的刷新效果太明显了，浏览器的刷新按钮会转动，而且页面也会闪动一下，所以还是不要使用它。可以看C:\git\github\shangguigu-learn\Codevolution\NextJS\nextjs实践\list-search-pagination\src\app\users\page.tsx这个页面的搜索例子。

另外，不要忘记了最新的'use cache'，因为我的博客肯定是不经常更新的，所以使用缓存是绝对没有问题的。

使用client components来实现

这个就比较简单了，就是路由所在page.tsx页面是server components，引入的search、table、pagination组件，都是client components。主要就是使用nuqs来修改url，然后使用react query监听query参数，当这些参数改变时，就重新请求数据。参考：C:\git\github\shangguigu-learn\Codevolution\NextJS\mycode\routing-demo\src\app\posts\page.tsx。

这个效果蛮好的，就是接口请求走的是客户端。

添加better-auth登录功能

项目在prisma配置好之后，就要配置better-auth，因为里面有User表，要按照它的来做，所以对后面的很多表都有影响，最先来做是最好的。

Better-Auth 的核心思想是将认证逻辑（Auth Handler, Server）和用户界面逻辑（Auth Client, React Hooks）分离，并利用 Next.js 的路由和中间件进行集成。

我先把整个流程讲解一下，后面再讲解具体操作：

流程

1、数据库模型定义 (Prisma Schema Definition)

这是整个认证系统的基石，作用是告诉 Better-Auth 数据应该以何种结构存储。

流程步骤	文件示例	作用
定义认证相关模型	`prisma/schema.prisma`	🌟 数据结构约定：你定义的 `User`, `Session`, `Account`, 和 `Verification` 四个核心模型，是 Better-Auth 适配器（Prisma Adapter）用来进行所有数据库操作的蓝图。它决定了用户的身份信息、登录状态、社交账号绑定（GitHub等）以及邮箱验证信息将如何与 PostgreSQL 交互和存储。

为什么它很重要？

Better-Auth 依赖于这些特定的模型来处理认证流程：

User: 存储用户的核心信息（id, name, email）。
Session: 存储用户的登录状态和有效期，与浏览器 Cookie 配合使用。
Account: 存储用户绑定的外部账号信息（如 GitHub 的 providerId 和 accountId），以及邮箱密码的哈希值。
Verification: 用于存储邮箱验证码或密码重置链接的凭证。

为什么按照它的方式来创建这些表呢？我想创建自己的User表不行吗？因为better-auth的原理是这样的：

Better-Auth 的核心实现原理是基于 Tokenless Session Management (无令牌会话管理)，结合 Prisma 数据库适配器 来实现全栈身份验证。它遵循了现代 Web 应用中常见的 Session Cookie 机制。
Better-Auth 的三大核心原理
1. Tokenless Session Management（无令牌会话管理）
Better-Auth 避免使用 JWT (JSON Web Tokens) 这种需要在每个请求中传输大量用户数据的传统方式。它的原理更接近于传统的基于 Cookie 的会话：
登录时生成会话： 用户登录成功后，Better-Auth 会在数据库的 Session 表中创建一个唯一的会话记录。
颁发安全 Cookie： Better-Auth 然后会创建一个安全的、加密的 Session ID，并将其作为 Cookie 发送到用户的浏览器。这个 Cookie 只包含一个指向数据库中会话记录的随机 ID。
验证会话： 在后续的请求中，服务器（包括 Next.js 的服务端组件或 API 路由）通过读取这个 Cookie 中的 ID，然后去数据库中查找完整的会话记录。如果记录存在且未过期，则用户身份得到验证。
优势： 这种方式的安全性更高，因为用户数据（如角色、权限）只存储在服务器端的数据库中，而不是暴露在客户端的 Cookie 中。如果需要吊销会话或更改用户权限，可以直接在数据库中操作，即时生效。

2. Prisma Adapter（数据库适配器）
Better-Auth 通过 prismaAdapter 将其认证流程与您的 PostgreSQL 数据库连接起来：
抽象化操作： Better-Auth 核心库不需要知道您的数据库是 PostgreSQL 还是 MySQL，它只依赖于适配器提供的一组标准 CRUD (增删改查) 函数。
模型映射： 适配器负责将 Better-Auth 内部需要的操作（如 createUser, createSession）转换为 Prisma Client 能够理解的、针对您的 User, Session, Account 等模型的具体查询。
3. Next.js 集成机制
Better-Auth 利用 Next.js 的特点，实现服务端和客户端的无缝衔接：
API Route Handler ([...all]/route.ts)： 这是认证逻辑的入口。Better-Auth 的核心处理函数 (auth.handler) 被封装在 Next.js 的 API 路由中。所有登录、登出、OAuth 回调等操作都通过这个单一路由进行处理。
React Hooks (useSession)： 在客户端，useSession Hook 通过调用 Better-Auth 的 Session API 路由来获取当前会话状态。它管理了 Loading 状态和会话的刷新，使得在 React 组件中获取用户状态变得非常简单。
服务端 (auth.api.getSession)： 在 Next.js 的 Server Components 或 Middleware 中，可以直接访问原始的 Request Headers 来读取 Session Cookie，然后服务器直接进行数据库查询验证，确保了高性能的 SSR/SSG。
简而言之，Better-Auth 的实现原理就是：利用安全的 Session Cookie 作为密钥，通过 Prisma 适配器连接到您的数据库，在服务器端进行身份验证和数据管理，并在 Next.js 的 Server/Client 组件中提供便捷的 Hooks 来消费这些认证状态。

2、后端配置与数据库集成 (Server Setup)

流程步骤	文件示例	作用
初始化 Better-Auth 实例	`lib/auth.ts`	🌟 定义认证规则：这是 Better-Auth 的核心，负责告诉系统如何工作。它配置了：1. 数据库适配器（如 Prisma），用于存储用户、Session 和 Account 数据。2. 认证策略（如 Email/Password, GitHub, Google），用于定义用户登录的方式。

3、API 路由集成 (API Handler)

流程步骤	文件示例	作用
创建认证 API 路由	`app/api/auth/[...all]/route.ts`	🌟 处理所有认证请求：这个 Catch-all 路由（`[...all]`）将所有发送到 `/api/auth/*` 的请求（如登录、注册、OAuth 回调、登出等）转发给 Better-Auth 的 Handler 进行处理。它将 Better-Auth 的核心逻辑暴露给 Next.js 应用程序。

因为打开页面的时候，nav或header上面的auth-user-menu组件会使用useSession()来查看是否登录了，所以会触发/api/auth/get-session接口调用，这个是better-auth帮我们做的。还有登录、登出的接口，都是这样的形式：/api/auth/xxxxxxxx，所以这里就需要有这个文件，让触发这些接口的时候，转交给better-auth进行处理。

4、前端客户端配置 (Client Setup)

流程步骤	文件示例	作用
创建 Auth Client 实例	`lib/auth-client.ts`	🌟 封装前端交互方法：基于后端配置，创建一个客户端实例。它导出了供 React 组件使用的便捷方法，例如 `signIn`, `signUp`, `signOut` 以及最重要的 `useSession` Hook。登录、登出、注册、查看是否登录，用到的就是这些方法。这里配置好了之后，在各个组件里面引入使用即可，非常方便。

5、前端组件与会话管理 (Usage & Session Management)

流程步骤	文件示例	作用
组件中使用 Hook	`app/page.tsx` (Client Component)	🌟 管理用户状态和 UI 切换：通过 `useSession()` Hook，组件可以获取当前用户的登录状态、用户信息（`session.user`）和加载状态。这是实现“登录/登出”按钮切换、显示用户名称、以及在客户端保护路由的基础。
服务端获取 Session	`app/dashboard/page.tsx` (Server Component)	🌟 在服务端渲染时获取用户信息：在 Next.js 13/14 的服务端组件中，可以直接调用 `auth.api.getSession()`，通过读取 Request Headers 中的 Cookie 来预先获取会话信息，实现高效的 SSR 或 SSG。

6、编写登录界面

上面的1-4步做好之后，其余的都好说了。

①创建一个登录组件，就是显示登录、登出的button样式的组件，放到nav栏上。里面使用useSession()来查看是否已登录。如果点击登录，就跳转到/sign-in页面；如果点击登出，就调用auth-client里面暴露的signOut方法即可。

②编写app/(auth)/sign-in/page.tsx页面，这个页面UI按照需求编写即可，完全可以是一个普通的form页面。重点是提交表单的时候，要调用auth-client暴露的signIn方法来登录。

③在sign-in页面中，可以加一个跳转链接，跳转到app/(auth)/sign-out/page.tsx页面，这个页面UI也是一个普通的form页面。重点是调用auth-client暴露的signUp方法来注册。

操作

参考https://www.better-auth.com/docs/installation，但是没有专门的nextjs相关的，所以需要结合AI来做。

1、安装依赖npm install better-auth

2、设置环境变量

在.env里面添加：


xxxxxxxxxx
2
1
BETTER_AUTH_SECRET=EdIDdrNFl6KnGkF0Hh3WC00lx8h8a3tg
2
BETTER_AUTH_URL=http://localhost:3000

如果需要添加github登录，需要获取GITHUB OAuth凭证后添加：

去 GitHub Developer Settings -> New OAuth App。

Homepage URL: http://localhost:3000

Authorization callback URL: http://localhost:3000/api/auth/callback/github

获取 Client ID 和 Client Secret。


xxxxxxxxxx
3
1
# GitHub OAuth
2
GITHUB_CLIENT_ID=你的Client_ID
3
GITHUB_CLIENT_SECRET=你的Client_Secret

3、创建better-auth实例，配置数据库及prisma适配器

创建/app/lib/auth.ts文件。加入邮箱密码、GitHub 登录支持和 Prisma 适配器配置。


xxxxxxxxxx
25
1
// app/lib/auth.ts
2
3
import { betterAuth } from "better-auth";
4
import { prismaAdapter } from "better-auth/adapters/prisma";
5
import { prisma } from "./lib/prisma";
6
7
export const auth = betterAuth({
8
  // 配置数据库和prisma适配器
9
  database: prismaAdapter(prisma, {
10
    provider: "postgresql", 
11
  }),
12
  // 允许邮箱密码登录
13
  emailAndPassword: {  
14
    enabled: true, // 启用邮箱密码
15
  },
16
  // 社交账号支持，这里启用了github账号的支持
17
  socialProviders: { 
18
    github: { 
19
      clientId: process.env.GITHUB_CLIENT_ID as string, 
20
      clientSecret: process.env.GITHUB_CLIENT_SECRET as string, 
21
    }, 
22
  },
23
  // 配置密钥
24
  secret: process.env.BETTER_AUTH_SECRET,
25
});

4、创建better-auth相关的数据库

先安装依赖pnpm add -D @better-auth/cli，这个依赖是用来生成ORM schema的。

然后使用npx @better-auth/cli generate命令来生成model，这个会在现有的schema.prisma里面追加model，可以根据项目需要添加一些字段，但生成的字段最好全部保留。

如果不想使用这种方式，想直接定义model，可以参考：https://www.better-auth.com/docs/concepts/database#core-schema，按照里面来定义即可。

5、API路由集成

创建/app/api/auth/[...all]/route.ts文件，将代码copy进去即可。这个文件就是帮助我们处理better-auth相关的接口。

6、创建better-auth客户端实例

client实例，可以帮助我们与auth服务进行交互，实例上的signIn方法可以帮助我们登录，signOut方法可以帮助我们登出，useSession方法帮助查询是否已登录等等。

这样我们就不用自己定义API接口了，直接使用这些方法即可。


xxxxxxxxxx
9
1
// app/lib/auth-client.ts
2
3
import { createAuthClient } from "better-auth/react";
4
5
export const authClient = createAuthClient({
6
  baseURL: process.env.BETTER_AUTH_URL,
7
});
8
9
export const { signIn, signOut, useSession, signUp } = authClient;

7、编写登录功能

better-auth客户端实例的方法，使用范例在这里：https://www.better-auth.com/docs/basic-usage。

因为nextjs只能做一些简单项目，所以不要担心更复杂的权限，先把这种权限掌握好即可。

light和dark主题转换

使用next-themes库。设置一个 ThemeProvider 组件来包裹您的应用，并使用 useTheme 钩子来切换主题。这个库能自动处理系统偏好设置，并防止页面闪烁。

1、首先在app/layout.tsx里面添加ThemeProvider。

2、编写一个toggle-mode组件，用来切换主题

3、在nav或header上面添加toggle-mode组件，因为这个组件使用了Provider，所以看上去是在别处操作，但是会作用到全局。这就是Provider的好处。

疑问：next-themes是怎么设置dark mode的呢？


xxxxxxxxxx
7
1
<ThemeProvider
2
    attribute="class"
3
    defaultTheme="system"
4
    enableSystem
5
    disableTransitionOnChange>
6
    {children}
7
</ThemeProvider>

next-themes 的核心功能是根据当前选择的主题（例如 'light', 'dark', 或 'system'）来动态地给根 HTML 元素 (<html>) 添加或移除一个 CSS class。

配置 attribute: 当您在 ThemeProvider 中设置 attribute="class" 时，next-themes 知道要操作 class 属性。
应用 Class:
- 如果用户选择了深色模式，它会在 <html> 标签上添加 class="dark"。
- 如果用户选择了浅色模式，它通常会确保没有 dark class，或者根据配置添加 class="light"。
CSS/Tailwind 的响应: 您的 CSS 样式（特别是使用 Tailwind CSS 时）会监听这个 class。例如，Tailwind CSS 的 dark: 变体样式仅在父元素或祖先元素有 .dark class 时才会被应用。

获取数据时，怎么处理loading和error

这里只谈论GET请求，因为create、update、delete这些请求都会使用server actions来处理，里面会用到useActionState，处理loading和error就比较简单。

我会经常写这样的代码：


xxxxxxxxxx
15
1
// 1. 最常见：Server → Client 通过 props（推荐）
2
async function Page() {
3
  const data = await db.post.findMany()   // 可以是 Date, Map 等复杂类型
4
5
  return <PostList posts={data} />        // 直接传！React 19 已经很宽容了
6
}
7
8
// 'use client'
9
function PostList({ posts }: { posts: Post[] }) {
10
  return (
11
    <div>
12
      {posts.map(p => <PostItem key={p.id} post={p} />)}
13
    </div>
14
  )
15
}

那么这里的数据库请求，如果报错了，或者接口很慢，我该怎么处理？

1、使用loading.tsx来处理loading

这是全页面的效果，如果这个页面很大，而页面中别的部分在loading时可能看不到了，所以使用范围有局限。就算使用骨架屏效果，还是不好。

2、使用Streaming + 局部 Suspense来处理loading

这是nextjs v16最推荐的方式，处理的粒度很细。为需要的地方做一个骨架屏效果即可。


xxxxxxxxxx
26
1
// app/dashboard/page.tsx
2
import { Suspense } from 'react'
3
import PostList from './PostList'
4
5
export default function DashboardPage() {
6
  return (
7
    <div className="container py-8">
8
      {/* 静态部分立即显示 */}
9
      <header className="mb-8">
10
        <h1 className="text-3xl font-bold">仪表盘</h1>
11
        <p className="text-muted-foreground">欢迎回来</p>
12
      </header>
13
14
      {/* 异步数据部分独立 streaming */}
15
      <Suspense fallback={<PostsSkeleton />}>
16
        <PostList />
17
      </Suspense>
18
19
      {/* 其他立即可渲染的内容 */}
20
      <div className="mt-12">
21
        <h2>快速统计</h2>
22
        {/* ... */}
23
      </div>
24
    </div>
25
  )
26
}

3、使用try...catch + error.tsx来处理错误

在获取数据时，使用try...catch来处理可能出现的错误，然后使用error.tsx来展示错误和重试。

但是建议只在当你需要对某些特定错误做精细处理时才写try...catch，普通错误交给error.tsx来处理即可。这是因为 Next.js 官方有意把“严重错误”（网络断开、数据库挂了、代码 bug、超时等）统一交给 error.tsx 处理。还是看项目要求，不要想太多。


xxxxxxxxxx
23
1
// app/dashboard/PostList.tsx （加强版）
2
import { notFound } from 'next/navigation'
3
import { db } from '@/lib/db'
4
5
export default async function PostList() {
6
  try {
7
    const posts = await db.post.findMany({
8
      orderBy: { createdAt: 'desc' },
9
      take: 20,
10
    })
11
12
    return <PostListUI posts={posts} />
13
  } catch (error) {
14
    // 数据库连接失败、超时等严重错误 → 让 error.tsx 处理
15
    console.error('数据库查询失败:', error)
16
    throw error   // 抛出，让 error.tsx 捕获
17
  }
18
}
19
20
// 或者业务层面的“没找到”
21
if (!someCriticalData) {
22
  notFound()   // 会显示 404
23
}

nextjs里面组件间传参的方式有哪些？

1、URL传参

① params传参

场景：每个条目都有独立页面、需要 SEO。对应的是url上的params参数：/products/productId，就是这里的productId。

直接使用params来接收参数

dynamic params url示例：/products/1。因为params是异步的，所以要使用async...await或者use。在server components里面获取：


xxxxxxxxxx
10
1
// /app/products/[id]/page.tsx
2
3
export default async function ProductDetail({
4
    params
5
}:{
6
    params: Promise<{id: string}>
7
}) {
8
    const id = (await params).id;
9
    return (...)
10
}

在client components里面获取。client components里面不能使用async...await，所以需要使用react提供的use。


xxxxxxxxxx
13
1
// /app/products/[id]/page.tsx
2
3
"use client";
4
import { use } from "react";
5
6
export default function ProductDetail({
7
    params
8
}:{
9
    params: Promise<{id: string}>
10
}) {
11
    const id =  use(params.id);
12
    return (...)
13
}

catch all routes url示例：/docs/feature1/content1。因为params是异步的，所以要使用async...await或者use。在server components里面获取：


xxxxxxxxxx
10
1
// app/docs/[[...slug]]/page.tsx
2
3
export default async function ProductDetail({
4
    params
5
}:{
6
    params: Promise<{slug: string[]}>
7
}) {
8
    const slug = (await params).slug || [];
9
    return (...)
10
}

在client components里面获取。client components里面不能使用async...await，所以需要使用react提供的use。


xxxxxxxxxx
13
1
// app/docs/[[...slug]]/page.tsx
2
3
"use client";
4
import { use } from "react";
5
6
export default function ProductDetail({
7
    params
8
}:{
9
    params: Promise<{slug: string[]}>
10
}) {
11
    const id =  use(params.slug);
12
    return (...)
13
}

使用usePathname来接收参数只能在client components里面使用。返回的是完整的path路径生成的数组。


xxxxxxxxxx
14
1
// app/docs/[[...slug]]/page.tsx
2
3
"use client";
4
import { usePathname } from "next/navigation";
5
6
export default function ProductDetail() {
7
    const pathname =  usePathname();
8
    if(pathname.length === 1) {
9
        return ...
10
    } else if(pathname.length === 2){
11
        return ...
12
    }
13
    return (...)
14
}

② searchParams传参

场景：筛选/分页/排序/临时状态。对应的是url上的query参数：?page=3&sort=price-desc。


xxxxxxxxxx
24
1
// app/products/page.tsx
2
import { Suspense } from 'react'
3
import ProductList from './ProductList'
4
5
export default function ProductsPage({
6
  searchParams,
7
}: {
8
  searchParams: { [key: string]: string | string[] | undefined }
9
}) {
10
  // Server Component 可以直接读
11
  const page = Number(searchParams.page) || 1
12
  const sort = searchParams.sort as string || 'newest'
13
  const q = searchParams.q as string
14
15
  return (
16
    <div>
17
      <SearchFilters initialValues={{ q, sort }} />
18
      
19
      <Suspense fallback={<ProductsSkeleton />}>
20
        <ProductList page={page} sort={sort} query={q} />
21
      </Suspense>
22
    </div>
23
  )
24
}

2、props传参

简单数据、复杂数据都可以通过这种方式来传递。

一般的用法是这样的：


xxxxxxxxxx
15
1
// 1. 最常见：Server → Client 通过 props（推荐）
2
async function Page() {
3
  const data = await db.post.findMany()   // 可以是 Date, Map 等复杂类型
4
5
  return <PostList posts={data} />        // 直接传！React 19 已经很宽容了
6
}
7
8
// 'use client'
9
function PostList({ posts }: { posts: Post[] }) {
10
  return (
11
    <div>
12
      {posts.map(p => <PostItem key={p.id} post={p} />)}
13
    </div>
14
  )
15
}

但是如果使用了Suspense，那么就可以使用use来解包Promise。这种是v16时代经典。


xxxxxxxxxx
21
1
// 2. 流式 + Promise 写法（非常推荐！Next.js 16 时代经典）
2
async function Page() {
3
  const postsPromise = db.post.findMany()   // 不 await！
4
5
  return (
6
    <>
7
      <Suspense fallback={<Loading />}>
8
        <PostList postsPromise={postsPromise} />
9
      </Suspense>
10
      <OtherStaticContent />
11
    </>
12
  )
13
}
14
15
// 'use client'
16
import { use } from 'react'
17
18
function PostList({ postsPromise }: { postsPromise: Promise<Post[]> }) {
19
  const posts = use(postsPromise)           // 在客户端组件里解包 Promise
20
  // ... 渲染
21
}

3、通过Context传参

这个经常使用，读取和操作数据非常方便。但是只能在client components里面使用。


xxxxxxxxxx
25
1
// 3. Context（只能在 Client Component 树中使用）
2
'use client'
3
4
import { createContext, useContext, useState } from 'react'
5
6
const ThemeContext = createContext<any>(null)
7
8
export function ThemeProvider({ children }: { children: React.ReactNode }) {
9
  const [theme, setTheme] = useState('dark')
10
  return (
11
    <ThemeContext.Provider value={{ theme, setTheme }}>
12
      {children}
13
    </ThemeContext.Provider>
14
  )
15
}
16
17
export function useTheme() {
18
  return useContext(ThemeContext)
19
}
20
21
// 使用（必须在 Provider 下面）
22
function Button() {
23
  const { theme } = useTheme()
24
  // ...
25
}

4、zustand、redux等第三方库传参

这个暂时用不到。

服务端请求怎么调试

在 Next.js 的 App Router（Server Components）中，服务端发出的 fetch 请求不会出现在浏览器的 Network 面板里，这是目前（2025年底）框架的设计使然。但还是可以手动输出一些日志来调试。

1、在 next.config.js 里打开 fetch 日志（Next.js 内置，最方便）


xxxxxxxxxx
11
1
/** @type {import('next').NextConfig} */
2
const nextConfig = {
3
  logging: {
4
    fetches: {
5
      fullUrl: true,       // 显示完整 url
6
      hmrRefreshes: true   // 连热更新时缓存命中的请求也显示
7
    }
8
  }
9
}
10
11
module.exports = nextConfig

2、加上基本的错误捕获 + 丰富日志（强烈推荐）


xxxxxxxxxx
34
1
export default async function Home() {
2
  let data = null;
3
  let error = null;
4
5
  try {
6
    const start = Date.now();
7
    const res = await fetch("https://....", {
8
      cache: "no-store" // 方便调试
9
    });
10
    
11
    const duration = Date.now() - start;
12
    
13
    console.log("[FETCH]", {
14
      url: res.url,
15
      status: res.status,
16
      ok: res.ok,
17
      time: `${duration}ms`,
18
      cacheStatus: res.headers.get("x-nextjs-cache") || "unknown"
19
    });
20
21
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
22
23
    data = await res.json();
24
  } catch (err) {
25
    error = err;
26
    console.error("[FETCH_ERROR]", {
27
      message: err.message,
28
      stack: err.stack?.split("\n").slice(0, 5),
29
      cause: err.cause
30
    });
31
  }
32
33
  // ... 后面正常渲染
34
}

你会看到类似这样清晰的输出：


1
[FETCH] {
2
  url: 'https://random-word-api.herokuapp.com/word',
3
  status: 502,
4
  ok: false,
5
  time: '1243ms',
6
  cacheStatus: 'skip'
7
}
8
[FETCH_ERROR] {
9
  message: 'fetch failed',
10
  stack: [ ... ],
11
  cause: { code: 'ECONNRESET', ... }
12
}