chore: 初始化 React + TypeScript + SCSS + Ant Design 项目

2026-11-07 21:24:06 +08:00
commit 99b11d1a17
@@ -0,0 +1,77 @@
+# Antd Starter
+
+React + TypeScript + SCSS + Ant Design 的前端起始项目，使用 Vite 构建。示例页面演示了 Ant Design 组件、SCSS 变量与 mixin、CSS Modules 以及一键切换的暗色主题。
+
+## 技术栈
+
+| 能力 | 选型 | 版本 |
+| --- | --- | --- |
+| 构建工具 | Vite | 8.x |
+| 框架 | React | 19.x |
+| 语言 | TypeScript（严格模式） | 7.x |
+| 样式 | Sass + CSS Modules | 1.x |
+| 组件库 | Ant Design（含 @ant-design/icons） | 6.x |
+
+## 快速开始
+
+需要 Node.js 20.19+ 或 22.12+（Vite 8 的要求）。
+
+```bash
+npm install     # 安装依赖
+npm run dev     # 启动开发服务器，默认 http://localhost:5173
+```
+
+其他脚本：
+
+```bash
+npm run build      # 类型检查 + 生产构建，输出到 dist/
+npm run preview    # 本地预览 dist/ 构建结果
+npm run typecheck  # 仅做 TypeScript 类型检查
+```
+
+## 目录结构
+
+```
+.
+├─ public/                  # 静态资源，原样拷贝到构建产物
+├─ src/
+│  ├─ components/           # 可复用业务组件
+│  │  └─ DemoForm.tsx       # Ant Design 表单示例
+│  ├─ pages/                # 页面
+│  │  ├─ HomePage.tsx
+│  │  └─ HomePage.module.scss
+│  ├─ styles/
+│  │  ├─ _variables.scss    # 颜色、间距、圆角、断点等变量
+│  │  ├─ _mixins.scss       # 响应式、布局等 mixin
+│  │  └─ global.scss        # 全局基础样式
+│  ├─ App.tsx               # 主题 / 语言包 Provider 与页面外壳
+│  ├─ App.module.scss
+│  ├─ main.tsx              # 入口
+│  └─ vite-env.d.ts
+├─ index.html
+├─ tsconfig.json
+└─ vite.config.ts
+```
+
+## 约定与说明
+
+**路径别名**：`@` 指向 `src`，在 TypeScript（`tsconfig.json` 的 `paths`）和 Vite（`resolve.alias`）中都已配置，例如 `import DemoForm from '@/components/DemoForm'`。
+
+**样式**：
+
+- 全局变量用 `@use '../styles/variables' as *;` 引入，不要用已废弃的 `@import`。
+- 组件级样式使用 CSS Modules（`*.module.scss`），类名通过 `styles.xxx` 访问，避免全局污染。
+- 主题色通过 CSS 变量（`--app-bg`、`--app-text` 等）下发，定义在 `App.module.scss` 的 `.app` 与 `.app.dark` 中，自定义样式可随 antd 主题一起切换。
+
+**Ant Design**：
+
+- `ConfigProvider` 统一主题 token 与中文语言包（`antd/locale/zh_CN`）。
+- 主题切换使用 `theme.defaultAlgorithm` / `theme.darkAlgorithm`。
+- 通过 `App` 组件提供的 `App.useApp()` 获取 `message`、`notification`、`modal`，保证它们跟随当前主题上下文。
+- 组件按需引入，例如 `import { Button, Form } from 'antd'`。
+
+**构建拆分**：`vite.config.ts` 使用 Rolldown 的 `codeSplitting` 把 `react`、`antd` 拆成独立 chunk，便于长期缓存；antd 依赖体积较大，已相应放宽 chunk 体积告警阈值。
+
+## 下一步
+
+把 `src/pages/HomePage.tsx` 和 `src/components/DemoForm.tsx` 换成自己的页面即可。如需路由、状态管理或请求库，可自行添加 React Router、Zustand、TanStack Query 等依赖。