# 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 等依赖。

## 部署

推送到 `main` 分支会触发 Gitea Actions（`.gitea/workflows/deploy.yml`），自动构建 Docker 镜像并在本机滚动重启容器。

| 项目 | 值 |
| --- | --- |
| 生产域名 | https://demo.chener.ymen.site |
| 容器名 / 镜像 | `demo` |
| 宿主机监听 | `127.0.0.1:9121` → 容器 `80` |
| 反向代理 | Caddy（`/etc/caddy/Caddyfile`）自动签发证书 |

镜像为多阶段构建：`node:24-alpine` 里执行 `npm ci && npm run build`，产物交给 `nginx:1.27-alpine` 提供服务，`deploy/nginx.conf` 负责 SPA 回退与静态资源缓存策略。

本地手动验证构建：

```bash
docker build -t demo:latest .
docker run --rm -p 127.0.0.1:9121:80 demo:latest
```