98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# 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
|
||
```
|