构建、部署与维护

本文面向生成的单端项目；React 与 Vue 都在项目根目录操作，不需要另一框架、模板仓库或相邻 ug-ui 源码。默认部署在域名根路径，子路径部署需同时调整 Vite base、路由 basename/history base 和资源地址，不能只改其中一项。

本地连接后端

将 .env.example 复制为 .env.development.local，填写：

VITE_AUTH_PROVIDER=http
VITE_DATA_PROVIDER=http
VITE_ADMIN_EXAMPLES=false
VITE_API_BASE_URL=/api
VITE_ADMIN_API_URL=/api
UG_API_PROXY_TARGET=http://127.0.0.1:8080

在项目根执行 bun install、bun run dev。模板仓库则在所选 apps/react 或 apps/vue 放环境文件，并运行对应开发命令。修改环境后重启 Vite。

浏览器请求同源 /api，Vite 将其转发到目标服务并保留 /api 前缀。例如 /api/orders 对应 http://127.0.0.1:8080/api/orders。后端没有 /api 前缀时，在 vite.config.ts 的 proxy 中添加 rewrite: (path) => path.replace(/^/api/, "")；这是项目部署约定，不要修改业务页面 URL。UG_API_PROXY_TARGET 仅供开发服务器使用，不进入前端，也不负责生产代理。未设置时不启用代理。

Cookie 应适用于浏览器访问的域和路径。跨域后端下发固定 Domain 或本地 HTTP 收不到 Secure Cookie 时，需按开发环境配置后端或代理，不能靠页面存储伪造会话。生产使用 HTTPS；认证、CSRF 与最终授权由服务端保证。

生产构建

  1. 保留创建器输出的 vendor/，首次 bun install 后提交项目自己的 bun.lock；之后使用 bun install --frozen-lockfile。
  2. 将 .env.production.example 复制为 .env.production.local，认证和数据模式都为 http；API 通常仍用 /api，由生产网关转发。
  3. 执行 bun run check 和 bun run build。产物为 dist/。不要把开发用 demo/mock 写到跨模式加载的 .env.local；生产构建会拒绝演示模式。
  4. 将完整 dist/ 发布到静态服务，保留 THIRD_PARTY_NOTICES.txt。VITE_ 值是构建时公开配置，修改环境文件后必须重新构建；不能放密码、服务端令牌或密钥。

模板仓库构建命令为 bun run --cwd apps/react build 或 bun run --cwd apps/vue build，分别输出 apps/react/dist、apps/vue/dist。独立文档站由模板仓库 bun run build:docs 构建，输出 apps/docs/dist，不随业务项目生成。

静态服务与 API 转发

可从 configs/deploy/nginx.conf 起步。修改 server_name、root 与 proxy_pass，纳入你已有的部署配置；它不安装服务、不配置证书，也不自动发布。修改后在目标服务器执行 nginx -t，再按现有运维流程加载。示例默认 HTTPS 在入口网关终止，直接公网部署须补 TLS。

  • 业务地址如 /orders/123 刷新时返回 index.html；不存在的 /assets/ 文件必须返回 404。
  • /api 和 /api/ 路由独立代理，后端 401/403/404/500 不回退为 HTML；proxy_pass 不带尾斜杠时保留 /api 前缀。
  • 带内容哈希的 assets 可长缓存，index.html 应重新验证，避免升级后引用旧资源。部署切换宜原子进行，保留上一版完整产物以便回退。
  • 如果使用其他静态托管，设置相同的 SPA 回退和 API 转发；不要把静态站点预览成功当成后端已连通。

上线核对

按 接口合同 检查实际响应：登录 → 刷新恢复 → 无权限拒绝 → 新增/编辑/删除 → 刷新后数据仍在 → 退出后旧会话失效。再直接打开深层业务地址，核对静态资源和 API 路径。服务端必须校验权限、记录范围与数据约束；前端菜单隐藏不是鉴权。

这里只给操作步骤；构建与本地协议样例通过，不代表真实服务、TLS、Cookie、网关或界面已经验收。

后续升级

package.json 的 ugAdmin 保存 framework、templateVersion。创建前另记录模板的 Git 提交与未提交改动，创建后将完整项目纳入自己的版本管理；版本号本身不足以重建尚未发布的源码状态。

升级先阅读模板变更，用来源提交比较受影响的 app/shared/patterns 与工程配置，再合并必要修复。保留 project.ts、backend/ 和业务 modules 的项目修改，不重新生成覆盖。UI 的 vendor 是分发包，不是修改源码的位置；使用一组兼容的 core/web/所选框架包整体更新并重新安装、更新锁文件。仅发布包或 vendor 内容已更新，才算消费项目实际拿到组件修复。