快速开始

环境要求

• Node.js 22 或更高版本
• npm 10 或兼容版本
• Git
• 推荐使用 VS Code，并安装 Vue - Official、ESLint、Prettier 扩展

获取与启动

git clone <你的仓库地址> ace-admin-max
cd ace-admin-max
npm install
npm run dev

开发服务器默认监听 0.0.0.0:5173。浏览器访问 http://localhost:5173，登录页可选择演示账号，例如 superadmin / 111111。

npm run dev 会先执行 sync:libarchive，把压缩包解析所需的 worker 和 WASM 文件复制到 public/libarchive，然后启动 Vite。

常用命令

命令	说明
npm run dev	同步 libarchive 资源并启动开发服务器
npm run build	同步资源、运行 TypeScript 检查、执行生产构建
npm run build:only	跳过类型检查，仅执行生产构建
npm run typecheck	执行 vue-tsc -b
npm run lint	ESLint 检查
npm run lint:fix	自动修复可修复的 ESLint 问题
npm run format	使用 Prettier 格式化 src/
npm run preview	本地预览生产构建

演示模式如何工作

开发环境的请求基础地址强制使用当前页面源，接口 URL 指向 public/api/**/*.json。Vite 会直接返回静态文件，所以项目无需后端也能展示页面。

静态文件无法真正处理写请求，当前示例因此使用 GET 模拟 CRUD。连接真实后端时，应将查询改为 GET，新增改为 POST，更新改为 PUT/PATCH，删除改为 DELETE，并由服务端持久化数据。

首次二次开发建议

1. 修改 index.html、系统信息接口和主题默认值中的品牌信息。
2. 设置 .env.production 的 API 地址和部署基础路径。
3. 删除不需要的演示页面与公开 /test 路由。
4. 按后端接口修改 src/api，不要在 Vue 页面中直接调用 Axios。
5. 让后端下发当前用户菜单、操作权限和字典。
6. 提交前运行 npm run typecheck、npm run lint 和 npm run build。

常见启动问题

依赖安装失败

项目的 xlsx 来自 SheetJS CDN，而不是 npm registry。确认当前网络可以访问该地址，或将依赖替换为团队可访问的镜像/制品源。

页面能打开但接口 404

检查请求 URL 是否仍对应 public/api 中的文件；接入后端后检查 VITE_API_URL、反向代理和后端上下文路径。

刷新动态路由出现 404

History 路由要求 Web 服务器把不存在的静态路径回退到 index.html，参见 Nginx 与子路径部署。