Next.js 15 的光标 .mdc:保持服务器和客户端组件之间边界的规则
代理破坏 App Router 的地方
典型场景:要求 Cursor“在文章页面添加点赞按钮”。代理发现需要 useState 并将 "use client" 放在最顶部 app/blog/[slug]/page.tsx。该页面已编译,但现在其所有代码(包括文章标记)都进入客户端捆绑包,并且对页面内数据库的查询停止工作。第二种常见情况:代理为了一种类型而将 lib/db.ts 导入客户端组件,并且程序集崩溃,或者更糟糕的是,带有环境变量的模块最终出现在捆绑包中。
该模型不知道服务器和客户端之间的边界协议。在使用 App Router 文件时,需要将它们明确写入 Cursor 替换的规则中。
整个规则
创建文件.cursor/rules/next-server-client.mdc:
---
description: Границы Server/Client Components в Next.js 15 App Router
globs: app/**/*.tsx, app/**/*.ts, components/**/*.tsx, lib/**/*.ts
alwaysApply: false
---
# Server и Client Components
- По умолчанию каждый компонент в app/ — Server Component. Не добавляй "use client" без причины.
- "use client" ставится только в листовой интерактивный компонент (кнопка, форма, виджет),
никогда в page.tsx, layout.tsx, template.tsx.
- Если нужен хук (useState, useEffect, useRouter из next/navigation) — вынеси интерактивную часть
в отдельный файл components/<feature>/<Name>.client.tsx и импортируй его из серверного компонента.
- Пропсы из Server в Client Component должны быть сериализуемыми: строки, числа, boolean, null,
массивы, простые объекты, Date. Нельзя передавать функции, классы, экземпляры Map/Set с методами,
ORM-модели. Исключение — Server Actions (функции из файла с "use server").
- Модули с доступом к БД, секретам и файловой системе начинаются с `import "server-only";`.
- В Next.js 15 params и searchParams в page/layout — Promise: `const { slug } = await params;`.
cookies(), headers(), draftMode() — асинхронные, вызывай через await.
- Переменные окружения без префикса NEXT_PUBLIC_ доступны только на сервере. Не читай
process.env.SECRET в файлах с "use client".
- Серверный компонент можно передать в клиентский через children или другой проп-слот,
но нельзя импортировать серверный компонент внутри файла с "use client".globs 字段将规则的应用限制为 App Router 和库文件,因此在代理编辑(例如部署脚本)时不会污染上下文。 alwaysApply: false 表示该规则是通过匹配文件连接的,而不是在每个请求中连接的。
用代码支持规则
规则是模型提示,而不是测试。要捕获构建中的错误,请安装 server-only 包:
npm install server-only
// lib/db.ts
import "server-only";
import { Pool } from "pg";
export const pool = new Pool({ connectionString: process.env.DATABASE_URL });如果客户端模块甚至可以传递导入 lib/db.ts,next build 将停止并出现可理解的错误。对于相反的情况,有client-only包:它用于标记接触window或localStorage的代码。
代理的参考模式
在规则中或规则旁边放置一个代理将遵循的简短示例非常有用:
// app/blog/[slug]/page.tsx — Server Component
import { getPost } from "@/lib/posts";
import { LikeButton } from "@/components/blog/LikeButton.client";
export default async function PostPage({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
const post = await getPost(slug);
return (
<article>
<h1>{post.title}</h1>
<div dangerouslySetInnerHTML={{ __html: post.html }} />
<LikeButton postId={post.id} initialCount={post.likes} />
</article>
);
}// components/blog/LikeButton.client.tsx
"use client";
import { useOptimistic, useTransition } from "react";
import { likePost } from "@/app/actions/like";
export function LikeButton({ postId, initialCount }: { postId: string; initialCount: number }) {
const [count, addLike] = useOptimistic(initialCount, (c: number) => c + 1);
const [pending, startTransition] = useTransition();
return (
<button
disabled={pending}
onClick={() =>
startTransition(async () => {
addLike(null);
await likePost(postId);
})
}
>
♥ {count}
</button>
);
}// app/actions/like.ts
"use server";
import { pool } from "@/lib/db";
export async function likePost(postId: string) {
await pool.query("UPDATE posts SET likes = likes + 1 WHERE id = $1", [postId]);
}.client.tsx 后缀不是 Next.js 的要求,而是一种约定。但它允许您和代理通过文件名了解边界在哪里。
如何识别违规行为
- 构建错误表明该钩子仅在客户端组件中起作用意味着:在没有
"use client"的文件中调用该钩子。正确的反应是删除交互部分而不是标记整个父级。 - 函数无法传递到客户端组件的错误,除非它们标有
"use server"- 代理从服务器组件传递了处理程序。要么执行服务器操作,要么将处理程序移动到客户端组件内。 - 水合警告通常意味着服务器输出使用
Date.now()、Math.random()或window相关值。 - 可疑的大客户端包:使用
@next/bundle-analyzer运行ANALYZE=true并检查它是否包含任何仅应存在于服务器上的 Markdown 解析器或 SDK。
当这条规则多余时
如果项目完全在 Pages Router 上或者是 Vite 上的 SPA,则该规则毫无用处,只会浪费上下文。对于一个只有两页且没有底座的小型原型,一般规则中的一行就足够了。请记住:.mdc 降低了代理错误率,但不会取代 server-only 和 diff 审查。