# mainsibufont

**Repository Path**: nobyebye/mainsibufont

## Basic Information

- **Project Name**: mainsibufont
- **Description**: 学习
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 前端开发规则（Ant Design + ProComponents + Next.js）

### 1. 技术栈与版本约定

- 框架：Next.js 14（App Router）
- UI 库：Ant Design
- ProComponents：仅在 **与当前 antd 版本兼容** 的前提下使用
  - 如需使用 ProComponents，优先选择 **antd 5.x + 对应版本的 @ant-design/pro-components**
  - 保持 `antd` 与 `@ant-design/pro-components` 的版本匹配，避免 npm 依赖冲突

### 2. 依赖安装规范

- **ProComponents 安装（仅在需要时使用）**
  - 安装前必须确认当前 `antd` 版本满足 `@ant-design/pro-components` 的 peerDependencies 要求。
  - 推荐组合：`antd@^5.11.2` 搭配对应版本的 `@ant-design/pro-components`。
  - 示例命令（仅在确认兼容后执行）：

    ```bash
    npm i antd@^5.11.2 @ant-design/pro-components --save
    ```

---

### 3. Next.js 路由规范（App Router）

- **约定式路由**
  - 以 `app` 目录作为路由根目录。
  - 目录下直接包含 `page.tsx` / `page.ts` / `page.jsx` / `page.js` 的文件才会被识别为路由。
  - 示例：
    - `app/page.tsx` → `/`
    - `app/dashboard/page.tsx` → `/dashboard`
    - `app/dashboard/settings/page.tsx` → `/dashboard/settings`

- **路由组（Route Group）**
  - 使用括号创建路由组目录，例如：`app/(shop)/layout.tsx`。
  - 路由组目录 **不会出现在 URL 中**，但可以在该组内复用一套 `layout`。
  - 示例：
    - 结构：`app/(shop)/account/page.tsx` → `/account`
    - 结构：`app/(shop)/cart/page.tsx` → `/cart`

- **动态路由**
  - 使用中括号定义动态段，例如：`[questionId]`。
  - 示例：

    ```tsx
    // app/question/[questionId]/page.tsx
    export default function Page({ params }: { params: { questionId: string } }) {
      return <div>我的题目：{params.questionId}</div>;
    }
    ```

  - 对应 URL 如：`/question/1`、`/question/2` 等，`params.questionId` 即为动态参数。

---

### 4. 静态资源与 Image 使用规范

- **静态资源目录**
  - 所有静态资源（图片、图标等）统一放在 `public/` 目录下，可按需建立子目录（如 `public/assets`）。
  - Next.js 会对 `public` 下的资源进行静态托管。

- **使用 `next/image` 加载图片**
  - 必须优先使用 `next/image` 组件加载图片，以获得自动优化。
  - 示例：

    ```tsx
    import Image from "next/image";

    export default function Logo() {
      return <Image src="/assets/logo.png" alt="logo" width={64} height={64} />;
    }
    ```

---

### 5. 站点元信息与 SEO 文件规范

- **图标（favicon / icon / apple-icon）**
  - 文件放置位置遵循 Next.js 约定：
    - `app/favicon.ico`：站点 favicon 图标。
    - `app/icon.(ico|jpg|jpeg|png|svg)`：站点或路由图标。
    - `app/apple-icon.(jpg|jpeg|png)`：Apple 设备桌面图标。
  - 图标文件可按路由层级放在对应目录下，复用 Next.js 的约定。

- **robots.txt 与 sitemap**
  - `app/robots.txt`：用于约束搜索引擎爬虫访问规则。
  - 示例内容：

    ```txt
    User-Agent: *
    Allow: /
    Disallow: /private/

    Sitemap: https://mianshiya.com/sitemap.xml
    ```

  - sitemap 建议通过后端或 Next.js Route Handler 动态生成，路径与线上域名保持一致。

---

### 6. 文件组织形式

- 每个页面与每个较大的组件，**使用独立目录** 管理：
  - 页面目录：使用 Next.js 约定式路由，在对应目录下放置 `page.tsx` 页面文件和对应样式文件（如 `index.css` 或 `page.module.css`）。
  - 组件目录：每个组件目录内建议放置 `index.tsx` 与对应样式文件（如 `index.css` / `index.module.css`）。
- 公共组件与页面私有组件的放置位置：
  - 项目级公共组件：统一放在 `src/components` 目录下，可按业务再分子目录。
  - 某个页面私有的组件：放在该页面目录下的 `components` 子目录，例如 `app/question/components/QuestionHeader.tsx`。

---

### 7. 页面与组件开发规范

- **客户端 / 服务端组件声明**
  - 为了区分服务端渲染与客户端渲染，每个页面或组件在需要时应在文件开头显式声明：
    - 客户端组件：`"use client";`
    - 服务端组件：默认即为服务端组件，如需强调可使用 `"use server";`。

- **页面编写规范**
  - 使用 React 函数组件语法定义页面。
  - 页面根元素建议包含唯一的 `id`，便于定位与调试。
  - 示例：

    ```tsx
    "use client";
    import "./index.css";

    export default function HomePage() {
      return (
        <main id="homePage">
          <div>布说</div>
        </main>
      );
    }
    ```

- **组件编写规范（TypeScript）**
  - 定义组件时必须使用 TypeScript 为 Props 声明类型。
  - 示例：

    ```tsx
    "use client";
    import "./index.css";

    interface Props {
      value?: string;
    }

    const MdViewer = (props: Props) => {
      const { value = "" } = props;

      return <div className="md-viewer">{value}</div>;
    };

    export default MdViewer;
    ```

---

### 8. 其他注意事项

1. **严格关注 TypeScript 提示与构建错误**
   - 开发过程中要及时修复 TypeScript 的类型错误和编译器报错。
   - 定期执行打包构建（`npm run build`），因为 Next.js 构建规则较严格，小问题也可能在构建阶段失败。

2. **谨慎使用仅浏览器环境支持的对象**
   - 服务端渲染阶段无法访问 `window`、`document` 等浏览器对象。
   - 若必须使用这些对象，确保组件声明为客户端组件（`"use client"`），并在副作用中安全访问（如 `useEffect`）。
   - 确保客户端渲染与服务端渲染输出结构一致，避免 hydration 报错。