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

Con trỏ .mdc cho Next.js 15: quy tắc giữ ranh giới giữa Thành phần Máy chủ và Máy khách

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

Trường hợp tác nhân phá vỡ Bộ định tuyến ứng dụng

Tình huống điển hình: yêu cầu Con trỏ “thêm nút thích vào trang bài viết”. Nhân viên hỗ trợ thấy rằng useState là cần thiết và đặt "use client" ở trên cùng app/blog/[slug]/page.tsx. Trang biên dịch, nhưng bây giờ tất cả mã của nó, bao gồm cả đánh dấu bài viết, đi vào gói ứng dụng khách và truy vấn tới cơ sở dữ liệu bên trong trang ngừng hoạt động. Trường hợp phổ biến thứ hai: tác nhân nhập lib/db.ts vào thành phần máy khách vì một loại và quá trình lắp ráp gặp sự cố hoặc tệ hơn là một mô-đun có các biến môi trường kết thúc trong gói.

Mô hình không biết các thỏa thuận ranh giới của bạn giữa máy chủ và máy khách. Chúng cần được viết rõ ràng thành quy tắc mà Con trỏ thay thế khi làm việc với các tệp Bộ định tuyến ứng dụng.

Toàn bộ quy tắc

Tạo tệp .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".

Trường globs giới hạn việc áp dụng quy tắc cho Bộ định tuyến ứng dụng và các tệp thư viện, do đó, trường này không gây ô nhiễm bối cảnh khi tác nhân chỉnh sửa, chẳng hạn như tập lệnh triển khai. alwaysApply: false có nghĩa là quy tắc được kết nối bằng các tệp phù hợp chứ không phải trong mọi yêu cầu.

Hỗ trợ quy tắc bằng mã

Quy tắc là một gợi ý mẫu, không phải là một bài kiểm tra. Để phát hiện lỗi trong bản dựng, hãy cài đặt gói 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 });

Nếu mô-đun máy khách thậm chí còn nhập tạm thời lib/db.ts, next build sẽ dừng với một lỗi có thể hiểu được. Đối với trường hợp ngược lại thì có gói client-only: dùng để đánh dấu đoạn mã chạm vào window hoặc localStorage.

Mẫu tham chiếu cho đại lý

Sẽ rất hữu ích nếu đặt một ví dụ ngắn trong quy tắc hoặc bên cạnh nó mà tác nhân sẽ tuân theo:

// 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]);
}

Hậu tố .client.tsx không phải là yêu cầu của Next.js mà là một quy ước. Nhưng nó cho phép cả bạn và tác nhân hiểu được tên tệp có đường viền.

Cách nhận biết vi phạm

  • Lỗi build cho biết hook chỉ hoạt động trong Client Component nghĩa là: hook được gọi trong một file không có "use client". Câu trả lời đúng là loại bỏ phần tương tác thay vì gắn cờ toàn bộ phụ huynh.
  • Lỗi không thể chuyển các chức năng tới Thành phần máy khách trừ khi chúng được đánh dấu bằng "use server" - tác nhân đã chuyển một trình xử lý từ thành phần máy chủ. Thực hiện Hành động máy chủ hoặc di chuyển trình xử lý bên trong thành phần máy khách.
  • Cảnh báo hydrat hóa thường có nghĩa là đầu ra của máy chủ sử dụng các giá trị phụ thuộc Date.now(), Math.random() hoặc window.
  • Gói ứng dụng khách lớn đáng ngờ: chạy ANALYZE=true với @next/bundle-analyzer và kiểm tra xem nó có chứa bất kỳ trình phân tích cú pháp đánh dấu hoặc SDK nào chỉ tồn tại trên máy chủ hay không.

Khi quy tắc này dư thừa

Nếu dự án hoàn toàn nằm trên Pages Router hoặc là SPA trên Vite thì quy tắc này sẽ vô ích và chỉ lãng phí bối cảnh. Đối với một nguyên mẫu nhỏ có hai trang và không có phần đế, một dòng trong quy tắc chung là đủ. Và hãy nhớ: .mdc làm giảm tỷ lệ lỗi của tác nhân, nhưng không thay thế server-only và xem xét khác biệt.

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

Ещё на vbcd4u.com