v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:01:00.000Z▲ 0 upvotes

Next.js 15 的光标 .mdc:保持服务器和客户端组件之间边界的规则

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

代理破坏 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 审查。

Обсуждение (0)

Ещё на vbcd4u.com