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 的要求）。
npm install # 安装依赖
npm run dev # 启动开发服务器，默认 http://localhost:5173
其他脚本：
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 回退与静态资源缓存策略。
本地手动验证构建：
docker build -t demo:latest .
docker run --rm -p 127.0.0.1:9121:80 demo:latest