Antd Admin 实战指南：用 init-antd-admin 脚手架快速搭建企业级后台，掌握模板特性与 CLI 原理

Antd Admin 实战指南用 init-antd-admin 脚手架快速搭建企业级后台掌握模板特性与 CLI 原理【免费下载链接】antd-adminAI-friendly enterprise front-end best practices项目地址: https://gitcode.com/gh_mirrors/an/antd-adminAntd Admin 是一个面向 AI 友好的企业级前端最佳实践仓库它提供开箱即用的生产级后台管理模板basic英文版与with-lingui中英双语版并通过init-antd-admin脚手架 CLI 让开发者一键生成独立可运行的工程。本文以仓库根目录 README.md 为核心骨架结合 packages/create 脚手架源码与apps/basic模板实现系统讲解模板的核心能力、CLI 的完整用法、底层实现原理以及脚手架化之后的标准开发工作流读完即可上手搭建并理解整个工具链的运转方式。项目概览两个模板 一个脚手架Antd Admin 以 monorepopnpm workspace turbo形式组织核心交付物分为两部分可复用的模板应用apps/basic纯英文环境与apps/with-lingui基于 Lingui 的enzh双语环境两者都是生产风格production-style的后台模板——包含真实项目的登录鉴权、权限菜单、CRUD 列表、主题切换、Mock 接口与测试覆盖而非玩具级 Demo。脚手架 CLI发布在 npm 上的init-antd-admin源码位于 packages/create。它在安装时从官方 monorepo 拉取上述模板思路与 create-turbo 类似并重写项目名、安装依赖、初始化 git最终产出独立standalone的应用工程。仓库中还有apps/docsNextra 技术文档站与docs/specs设计与实现说明文档例如 create-antd-admin 设计文档、with-lingui 优化计划可作为深入理解架构的一手资料。核心特性一览根据根 README.md 的官方表述模板具备以下关键能力特性说明JWT 登录access / refresh 双 token 的登录流程后端驱动菜单与权限菜单由数据驱动配合权限守卫RBAC与 403 页面URL 同步表格状态分页、排序、搜索关键词与 URL 查询参数双向同步可分享、可回退暗色主题切换基于 Ant Design theme algorithm 的一键暗色模式Mock-first 开发本地开发完全依赖 MSWService Worker拦截 API无需真实后端即可全功能跑通类型化 API 边界Zod schema 约束接口契约复用型 CRUD 模式现代技术栈React 19 Ant Design 6 TanStack Router/Query Zustand Zod可选 i18nwith-lingui模板提供基于 Lingui 的双语工作流E2E 覆盖Playwright 端到端测试这些特性在apps/basic中均有对应的源码落点apps/basic/src/api/存放 Zod 模型与接口契约apps/basic/src/hooks/提供useResourceCRUD、useUrlSearchState、usePermission、useAppTheme等核心 hookapps/basic/src/mocks/handlers/是 MSW 的 mock 处理器apps/basic/e2e/则是 Playwright 测试套件覆盖登录、用户 CRUD、token 刷新、RBAC、URL 状态等场景。快速开始脚手架使用全攻略前置要求脚手架要求Node.js ≥ 20见 packages/create/package.json 的engines字段。由于模板基于 ViteVoidZero 统一工具链构建建议同时准备好pnpm。交互式创建任选一种包管理器对应的执行方式npx init-antd-adminlatest pnpm dlx init-antd-adminlatest yarn dlx init-antd-adminlatest bunx init-antd-adminlatest进入交互模式后CLI 会依次询问对应 prompts.ts 的实现选择模板Which example do you want?从发布时生成的examples.json清单中选择例如basic、with-lingui目标目录Project directory?默认my-antd-admin支持相对路径或.当前目录此时会二次确认npm 包名npm package name for package.json?带校验非法包名会即时报错提示包管理器从 PATH 中自动检测可用项检测顺序为pnpm→npm→yarn→bun见 package-manager.ts供选择。交互确认完成后CLI 拉取模板 → 复制到目标目录 → 重写package.json的 name → 安装依赖 →git init最终打印Success! Project created at ...。非交互式无人值守创建pnpm dlx init-antd-adminlatest my-app --example basic -m pnpm pnpm dlx init-antd-adminlatest my-app --example with-lingui --skip-install第一条命令创建my-app目录使用basic模板包管理器指定为pnpm 第二条命令使用with-lingui模板并跳过依赖安装适合快速冒烟测试详见 packages/create/README.md。全部 CLI 选项下表整理了根 README 与 packages/create/README.md 中的完整参数并与 cli.ts 中 commander 的定义逐一对齐选项说明[project-directory]目标文件夹相对路径或.仅允许空目录-e, --example name|url模板短名如basic或直接的模板仓库 URL--example-path path使用 URL 时指定仓库内子路径-m, --package-manager pmnpm/pnpm/yarn/bun--skip-install脚手架完成后不执行依赖安装--skip-transforms跳过重写转换如package.json的 name--no-git不执行git init-v, --version打印 CLI 版本-h, --help打印帮助信息运行init-antd-admin --help可随时查看完整帮助文本。另有两个值得注意的行为细节若同时使用--skip-transforms与显式-mCLI 会打印黄色警告package.json的 name 可能在安装前未被更新目标目录非空时脚手架会直接报错中止对应 paths.ts 中resolveTargetRoot的空目录校验逻辑。CLI 底层原理从命令参数到项目落地的完整链路理解 CLI 的实现有助于排障与二次开发。init-antd-admin的入口是 cli.ts由 commander 解析参数后调用 commands/create.ts 中的runCreate其核心流程如下加载模板清单读取构建产物dist/examples.json由 scripts/write-examples-json.mjs 在发布时扫描apps/目录自动生成排除apps/docs。若文件缺失或清单为空会提示先执行pnpm run build见 examples.ts。解析模板来源--example支持两种形态见 resolve-example-source.ts短名如basic拼接为github:zuiidea/antd-admin/apps/name#ref形式的 giget 源此时--example-path可作为apps/name下的子路径URL直接作为 giget 源使用--example-path拼接在 URL 之后。解析 Git ref见 resolve-ref.ts优先级为CREATE_ANTD_ADMIN_REF环境变量 → 本包package.json版本号生成的vversion标签 → 兜底main分支。这意味着模板默认从与 CLI 版本匹配的vversion标签拉取保证 CLI 与模板版本的兼容性。下载并复制通过 giget 下载到临时目录后cpSync复制到目标目录完成后清理临时目录。运行转换run-transforms.ts默认将目标package.json的 name 重写为交互输入或目录名推导的包名--skip-transforms可跳过。安装依赖按所选包管理器执行对应的install命令见 package-manager.ts 的spawnInstall--skip-install跳过。初始化 git--no-git可跳过。环境变量高级定制当需要从镜像仓库或特定版本拉取模板时可通过环境变量覆盖默认值见 constants.ts变量作用CREATE_ANTD_ADMIN_REPO覆盖仓库owner/name默认zuiidea/antd-adminCREATE_ANTD_ADMIN_REF覆盖 Git ref分支、标签或 commit SHA。默认取vcliVersion读不到版本文件时回退main这在私有化部署、离线镜像或验证未发布模板时非常实用。模板选择basic 与 with-lingui 的差异两者共享几乎相同的工程结构api / components / hooks / mocks / routes / stores / utils核心差异在于国际化apps/basic纯英文。界面文案直接以字符串形式散落在组件与路由中无 Lingui 目录与语言切换器Ant Design 固定使用en_USlocale。适合不需要多语言的国内/国际单一语言项目依赖更少、心智负担更低。apps/with-lingui基于 Lingui 的双语模板包含src/locales/en/messages.po与src/locales/zh/messages.po目录、lingui.config.ts配置以及loadLocaleCatalog.ts动态加载逻辑支持.po文件的提取/编译工作流与 Ant Design 组件库语言包的联动切换详见 with-lingui 模板 与 优化计划文档。从根 README 与 apps/basic/README.md 的表述可以推断选择策略是需要 i18n 就从with-lingui起步否则使用basic更加精简。脚手架之后模板内的标准开发工作流以apps/basic为例脚本定义见 apps/basic/package.json脚手架生成的工程遵循 Vitevp工具链约定安装与启动pnpm install pnpm run dev启动后访问http://localhost:5173会被重定向到登录页默认测试账号为admin/admin来自 apps/basic/README.md。得益于 Mock-first 设计此时所有接口请求都由 MSW 在浏览器侧拦截public/mockServiceWorker.jssrc/mocks/browser.ts无需启动任何后端服务。常用脚本命令用途pnpm run prepare生成路由配置vp config产出src/routeTree.gen.tspnpm run build类型检查 生产构建tsc vp buildpnpm run preview本地预览构建产物pnpm run fmt代码格式化pnpm run lint代码检查pnpm run check类型与 lint 联合校验vp check --no-fmtpnpm run test:unitVitest 单元测试覆盖 CRUD hook、MSW handler 等如 useResourceCRUD.test.ts、createHandler.test.tspnpm run test:e2ePlaywright 端到端测试pnpm run test:e2e:uiPlaywright 交互式 UI 模式模板内的页面与目录结构basic模板内置了/login、/dashboard统计概览卡片、/users带搜索、分页、增删改查的用户管理、/403、/404五个页面。其src/目录划分清晰api/Zod 模型与接口契约components/布局壳MainLayout、Header、Sidebar、UserMenu、AppFooter、DataTable 表格框架、FormModal 弹窗表单、FilterToolbar 列表工具栏、Auth 权限门组件、Aurora 登录页背景特效等hooks/useAppTheme暗色主题、usePermissionRBAC、useResourceCRUD通用 CRUD 流程、useUrlSearchStateURL 状态同步、useTableFitHeight、useCrudToastsmocks/MSW 启动与 handlers、种子数据、测试辅助工具routes/TanStack Router 文件路由__root.tsx统一装配 QueryClient 与 AntD ConfigProvider_auth.tsx为受保护路由布局stores/基于 Zustand 的持久化 auth / settings storeutils/HTTP 客户端、常量、session / 菜单辅助函数。对接真实后端模板默认全 Mock 运行接入真实后端只需两步见 apps/basic/README.md 的 Extending 一节在环境变量中配置VITE_API_BASE_URL指向真实服务在src/main.tsx中停用或移除 MSW 初始化。若需要多语言能力则直接以with-lingui模板为起点或参考其 Lingui 配置进行移植。在本仓库内开发与发布 CLI维护者视角对于希望贡献或二次开发脚手架的开发者packages/create/README.md 给出了完整的本地开发路径pnpm install cd packages/create pnpm run build pnpm test node dist/cli.js --help发布流程由 monorepo 内.github/workflows/publish-init-antd-admin.ymlCI 驱动要求仓库配置具备init-antd-admin发布权限的NPM_TOKEN密钥提升packages/create目录下package.json的版本号随后通过 Actions 手动触发发布或推送与版本号匹配的init-antd-admin-vversion标签同时在 monorepo 上推送匹配的vversion标签以便 CLI 默认模板 refv${version}可解析。默认拉取模板的 ref 与 CLI 版本强绑定这是保证脚手架拉到的模板始终与该 CLI 版本匹配的关键设计。总结Antd Admin 提供了一条从零配置启动到生产级后台的完整路径init-antd-admin负责一键生成独立工程支持交互式与非交互式、四种包管理器、模板定制与 git 初始化模板本身则内置了 JWT 鉴权、后端驱动 RBAC、URL 同步表格、暗色主题、MSW Mock、类型化 API 与 Playwright E2E 等企业后台的标配能力。选择basic纯英文还是with-lingui中英双语取决于你的国际化需求而理解 CLI 的参数解析、模板解析、ref 解析与环境变量机制则能让你在镜像、私有化与模板定制场景下游刃有余。本仓库遵循 MIT 协议所有模板与工具链均为开源可审计实现上述任何结论都可以在 README.md、packages/create、apps/basic/README.md 及对应源码中逐一验证。【免费下载链接】antd-adminAI-friendly enterprise front-end best practices项目地址: https://gitcode.com/gh_mirrors/an/antd-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考