nomo-web

Nomo Web

基于 React + TypeScript + Vite 的 H5 前端项目。

环境要求

• Node.js >= 18.20.7
• pnpm >= 9

快速开始

pnpm install --frozen-lockfile
pnpm dev

浏览器访问控制台输出的本地地址即可。

脚本说明

命令	说明
pnpm dev	本地开发（使用 .env.localdev + .env）
pnpm build	生产构建（等价于 build:prod）
pnpm build:dev	开发模式构建（.env.development）
pnpm build:prod	生产模式构建（.env.production）
pnpm build:test	测试环境构建（.env.test）
pnpm preview	预览构建产物（使用 localdev 模式）
pnpm lint / pnpm lint:fix	ESLint 检查 / 自动修复
pnpm stylelint / pnpm stylelint:fix	样式检查 / 自动修复

环境配置

通过不同 .env 文件区分环境，Vite 按 mode 加载：

文件	何时加载
.env	始终加载（公共默认）
.env.localdev	pnpm dev / pnpm preview（--mode localdev）
.env.development	pnpm build:dev
.env.production	pnpm build / pnpm build:prod
.env.test	pnpm build:test
.env.local	本地覆盖，除 test 外都会加载（一般不提交）

需在环境文件中配置的变量见 .env 内注释或项目文档。

技术栈

• 框架：React 18、TypeScript
• 构建：Vite 6、pnpm
• UI：Ant Design 5、Tailwind CSS、SCSS/Less
• 路由：React Router 7
• 状态：基于 Context + Hooks 的 Model 方案（类 Umi max）
• 国际化：i18next（zh-CN / en-US / fa-IR）
• 请求：Axios 封装（src/utils/request）
• 图标：@iconify/react + 自定义 SVG 转 Iconify 插件
• 规范：ESLint、Prettier、Stylelint、Commitlint、Husky、lint-staged

项目结构

├── build/              # Vite 构建相关（插件、工具）
├── public/             # 静态资源
├── src/
│   ├── assets/         # 资源
│   │   └── iconify/    # 单色 single-color、多色 multi-color 图标
│   ├── components/     # 公共组件
│   ├── config/         # 应用与请求配置（含 request 拦截器、错误处理）
│   ├── defines/        # 枚举与常量
│   ├── hooks/          # 公共 Hooks
│   ├── i18n/           # 国际化配置
│   ├── layouts/        # 布局
│   ├── locales/        # 多语言文案（zh-CN、en-US、fa-IR）
│   ├── models/         # 全局状态 Model
│   ├── pages/          # 页面（按页面分目录）
│   ├── router/         # 路由配置
│   ├── services/       # API 接口（按模块分目录）
│   ├── styles/         # 全局样式
│   ├── utils/          # 工具与 request 封装
│   ├── App.tsx
│   └── main.tsx
├── types/              # 全局类型与 env 类型
├── index.html
├── vite.config.ts
└── package.json

开发规范摘要

• 严格 TypeScript，遵循项目 ESLint/Prettier 配置
• 提交信息使用 Conventional Commits
• 组件：函数组件 + Hooks；样式优先 Tailwind，必要时 SCSS/Less
• 用户可见文案全部走 locales，禁止在代码中硬编码
• 常量与枚举放在 src/defines/，请求在 src/services/ 按模块组织
• 新页面：在 src/pages/ 下建目录、在 routes 与 locales 中注册

状态管理（Model）

• Model 定义在 src/models/，通过 createModel(hook, name) 创建。
• 在组件中：const user = userModel.useModel()，使用返回的状态与方法。
• 根组件已通过 autoImportModels 注入所有 Model 的 Provider。

详见 src/utils/model/ 与现有 userModel、dialogModel、userConfigModel 实现。

图标

• 单色图标：放入 src/assets/iconify/single-color/，会转为 currentColor，可用 className 控制颜色。
• 多色图标：放入 src/assets/iconify/multi-color/，保留原色。
• 使用：import icon from '@/assets/iconify/single-color/xxx.svg'，再 <Icon icon={icon} />（@iconify/react）。

多语言

• 文案在 src/locales/ 下按语言分目录（zh-CN、en-US、fa-IR），每语言含 common、components、menus、pages 等模块。
• 组件内：const { t } = useTranslation();，t('key') 或带命名空间的 key。
• 禁止在页面/组件中写死中文或英文字符串。

请求与接口

• 请求封装：src/utils/request，基础配置与拦截器在 src/config/request/（认证、加解密、错误处理）。
• 接口按模块放在 src/services/，每模块可有 typings.d.ts + index.ts。
• 调用：import { fetchXxx } from '@/services/xxx'，错误由统一错误处理兜底，可选 skipErrorHandler 自行处理。

本地存储

• src/utils/localUtils、src/utils/sessionUtils 提供 createLocalTools / createSessionTools，支持按 key/value 加密与命名空间。
• 通过环境变量配置加密密钥与存储命名空间，敏感数据建议开启加密选项。

部署

• 构建产物在 dist/，将对应环境（如 test/production）的构建结果部署到静态服务器或 CDN 即可。
• 多环境通过上述 build:dev / build:test / build:prod 与对应 .env.* 区分。