Skip to content

README.zh-CN.md

Latest commit

 

History

History
180 lines (127 loc) · 8.96 KB

README.zh-CN.md

File metadata and controls

180 lines (127 loc) · 8.96 KB

@guanzhu.me/arco-cli

用 Vite 7 + React 18 + 严格 TypeScript 在一分钟内搭起一个现代化的 Arco Design 管理后台。fork 自停更的 arco-cli，自带一套修正官方 arco-design-pro 老旧技术栈的现代化模板。

npm license node CI Demo

English · 中文 · 在线 Demo ↗ · 部署文档

Arco Pro 演示 —— 登录、主题切换、表格 mock 数据

Note

这是一个社区维护的 fork —— 非 Arco Design 团队官方出品。原来的官方模板（arco-design-pro、@arco-materials/*）仍可使用；真正的差异化在于内置的 "Arco Pro (Unofficial)" 模板。

为什么做这个

官方 arco-design-pro 是个很好的项目，但最后一次发版停留在 2024-04，技术栈开始过时。与此同时上游 arco-cli 也已弃维护，在新版 Node 上跑不动。

这个 fork 把 CLI 修好可用 加上 一套对 Arco Pro 做现代化重写的内置模板：

官方 arco-design-pro 内置 pro-recommend
构建 Webpack 4 / Vite 混用 Vite 7
React 16 18.3（等 Arco 修复 cloneElement(child.ref) 后再升 19）
TypeScript 宽松 strict + noImplicitOverride
服务端状态 手写 axios TanStack Query v5
客户端状态 redux-thunk Zustand v5（持久化）
表单 仅 Arco Form react-hook-form + zod，通过一个轻量 <Field> 桥接
Mock mockjs（已弃用） MSW v2 + @faker-js/faker
国际化 仅 Arco locale i18next + react-i18next
Lint ESLint legacy ESLint 9 flat config + 构建前 tsc --noEmit 卡口
测试 无 vitest + Playwright smoke E2E
包体分析 无 npm run analyze（rollup-plugin-visualizer）
依赖腐烂 死掉的 react-color、mockjs、query-string 等 清理完毕

此外：图表换成 VChart、路由级 + chunk 级代码分割、MSW 懒导入（生产 entry 从 ~1.15 MB 降到 ~289 KB）、通过 react-helmet-async 实现路由级 document title、react-error-boundary 在页面级别兜底、主题切换跟随 prefers-color-scheme。

快速开始

npx @guanzhu.me/arco-cli init my-app
cd my-app
npm install   # 如果上一步用了 --skip-install
npm run dev

或全局安装：

npm i -g @guanzhu.me/arco-cli
arco init my-app

交互式菜单会让你选模板，传 --template 跳过菜单：

arco init my-app --template pro-recommend          # 内置 Unofficial，full 预设
arco init my-app --template pro-recommend:simple   # 内置 Unofficial，dashboard-only 预设
arco init my-app --template arco-design-pro        # 官方（停留在 2024-04）

内置模板里有什么

src/
├── api/             # axios client + 按资源拆的 TanStack Query hook
├── auth/            # useAuth() + <ProtectedRoute> + <Access>/useAccess（RBAC + 细粒度 —— 见 docs/auth-backend.zh-CN.md）
├── components/      # NavBar、Chart 包装、Settings 抽屉、Form/Field 桥接
├── i18n/            # i18next 初始化（en + zh-CN）
├── layout/          # PageLayout、breadcrumb + 路由扁平化
├── mock/            # MSW worker + 中央 handler 注册
├── pages/           # dashboard / list / form / user / visualization / exception / welcome
├── store/           # Zustand store（settings）
└── style/           # global.less + Arco 主题 token
e2e/                 # Playwright smoke（登录、mock 数据、主题切换、404）

内置脚本：

脚本 作用
npm run dev Vite 开发服务，热更新
npm run build 先 tsc --noEmit 再 vite build
npm run typecheck 严格 TS 检查
npm run lint ESLint 9
npm test vitest 单测
npm run test:coverage v8 覆盖率报告
npm run analyze 包体可视化（sunburst stats.html）
npm run e2e Playwright smoke（自动启动 dev server）
npm run e2e:install 一次性下载 Chromium

其他 CLI 命令

给已有的 arco-design-pro 项目添加新页面：

arco add page user-list --type table
arco add page settings  --type blank

会生成 src/pages/<name>/{index.tsx,style/index.module.less,locale/index.ts}，当 src/routes.ts + src/locale/index.ts 是官方形态时，会交互式询问菜单位置并自动改这两个文件。否则会打印需要粘贴的代码片段。

--type 可选 blank（Card + title）或 table（带表头、操作按钮、Arco Table）。

一条命令生成 /api/<name> 的强类型 hook + zod schema + MSW mock：

arco add api user-list                   # → useUserListQuery（GET，列表形态）
arco add api user-create --method post   # → useUserCreateMutation
arco add api user --method delete --skip-mock

会生成 src/api/<name>.ts（zod schema、query keys、TanStack Query hook）和 src/mock/<name>.ts（faker 数据 + MSW handler），并自动改 src/mock/handlers.ts 注册新 handler。当 handlers.ts 形态与上游不一致时，CLI 会打印两行 import/spread 让你手贴。

一条命令生成完整 CRUD 模块 —— 页面 + 4 个 API hook + 可工作的 MSW handler：

arco add table user

创建 src/pages/user/{index.tsx,columns.tsx,form.tsx,locale/}、src/api/user.ts（list/create/update/delete 四个 hook）、src/mock/user.ts（handler 真的会改内存里的数组，POST 的行会在本次 dev 会话里持续可见）。同时自动改 src/routes.ts 添加顶层菜单、src/locale/{en-US,zh-CN}.ts 加菜单翻译、src/mock/handlers.ts 注册新 handler。跑完命令直接访问 /user，就有一个完整能用的表格 —— 搜索、翻页、新建/编辑 Drawer、删除，全部走 zod 校验。

其他工具：

arco dev                              # 转发到项目自己的 `npm run dev`
arco upgrade --version latest         # 升级 package.json 里的 Arco 依赖
arco init my-app --template file:../my-template   # 本地模板目录

自定义模板

模板就是一个 npm 包（或本地目录），内含：

  • 一个 template/ 目录（其中内容会被逐字复制），或
  • 一个 .arco-cli/init.js 脚本（导出 async 函数做自定义初始化逻辑）

可选的 hook/after-init.js 或 .arco-cli/after-init.js 会在 npm install 之后执行。

部署

在线 Demo → arco-pro-demo.vercel.app（admin / admin，其实随便填 —— mock 层不做校验）

想部署自己的 demo？看 部署文档 —— 涵盖 Vercel（点击式配置，就是在线 demo 跑的方案）、Cloudflare Pages 控制台、以及 GitHub Pages 备选。MSW 在浏览器拦截所有 /api/*，demo 完全不需要后端。

接真实后端

模板自带 <Access> / useAccess() 做权限控制，demo 通过 mock 提供 roles[] + permissions{}。要接真后端，看 docs/auth-backend.zh-CN.md —— 涵盖 UserInfo 契约、三种权限模型（纯 RBAC / 纯 ACL / 混合）、SQL 表设计、Node / Spring / FastAPI / Go 的中间件示例、Session vs JWT、数据级权限过滤，以及从既有 auth 迁移的清单。

运行要求

  • Node.js ≥ 22（LTS 线 22 和 24）
  • Windows + Linux 通过 CI；macOS 可用但未在 CI 验证

备注

CLI 内置了一个 child_process 兼容垫片，让那些直接调用 spawnSync('npm.cmd', …) 的老模板（比如 arco-design-pro）能在执行 BatBadBut（CVE-2024-27980）修复的 Node 版本上继续工作。

状态 / 路线

这是一个个人维护的开源项目 —— 通过打 tag 触发 npm publish（Trusted Publishing，无 secret）。近期重心在加固内置模板（严格 TS、现代化测试、清理死代码、mock bug 修复）。可能的后续方向（无固定顺序）：

欢迎提 issue 和 PR，架构和开发流程见 CONTRIBUTING.md 和 docs/。

License

MIT —— 见 LICENSE。