构建部署

这一页说明 apps/admin 如何构建和部署。重点是把命令、mode、env、Vite base、SPA history rewrite 和 Nginx 配置放在一起看，避免构建成功但线上刷新 404、资源路径错误或接口地址不对。

命令建议在仓库根目录执行。apps/admin 的 workspace 包名是 skyroc-admin。

适用场景

当前实现位置

构建前检查

当前仓库根要求：

先在仓库根安装依赖：

pnpm install

不要只在 apps/admin 目录单独安装依赖。apps/admin 使用多个 workspace 包，构建时需要 workspace 解析和本地包产物配合。

构建命令

生产环境构建：

pnpm --filter skyroc-admin build

实际执行：

vite build --mode prod

测试环境构建：

pnpm --filter skyroc-admin build:test

实际执行：

vite build --mode test

两个构建命令都会先执行对应的 prebuild 脚本：

pnpm run build:admin-vite

也就是先构建 @skyroc/web-admin-vite：

pnpm --filter @skyroc/web-admin-vite build

原因是 apps/admin/vite.config.ts 直接从共享包导入 defineConfig。构建应用前先构建共享 Vite 预设，可以确保本次构建使用的是最新的 preset 产物。

mode 和 env

脚本和 env 的关系如下：

VITE_SERVICE_BASE_URL、VITE_OTHER_SERVICE_BASE_URL、VITE_BASE_URL 这类变量会在构建时确定。修改 env 后必须重新构建，不能只替换静态文件目录里的某个 JS 文件。

预览构建产物

构建完成后，本地预览：

pnpm --filter skyroc-admin preview

@skyroc/web-admin-vite 的 preview 默认端口是 9725：

config.preview = {
  port: 9725,
  ...application.preview
};

如果要改 preview 端口，在 apps/admin/vite.config.ts 配置：

import { defineConfig } from '@skyroc/web-admin-vite';

export default defineConfig({
  application: {
    preview: {
      port: 4173
    }
  }
});

preview 只用于本地检查构建产物，不替代线上 Nginx、CDN 或对象存储配置。

部署到域名根路径

如果部署在域名根路径，例如：

https://admin.example.com/

保持：

VITE_BASE_URL=/

构建后把 Vite 输出目录部署到站点根目录。Vite 默认输出目录是 dist。

Nginx 最小配置：

server {
  listen 80;
  server_name admin.example.com;

  root /var/www/skyroc-admin/dist;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }
}

try_files 是必须的。当前 TanStack Router 使用默认 browser history，用户刷新 /manage/user 时，服务器需要回退到 index.html，再让前端路由接管。

部署到子路径

如果部署在子路径，例如：

https://example.com/admin/

先把 base 改成子路径：

VITE_BASE_URL=/admin/

然后重新构建：

pnpm --filter skyroc-admin build

Nginx 示例：

server {
  listen 80;
  server_name example.com;

  location /admin/ {
    alias /var/www/skyroc-admin/dist/;
    index index.html;
    try_files $uri $uri/ /admin/index.html;
  }
}

子路径部署时要同时满足两件事：

如果只改 Nginx，不改 VITE_BASE_URL，资源路径可能从域名根加载；如果只改 VITE_BASE_URL，不做 rewrite，刷新深层路由仍会 404。

后端接口和代理

开发环境代理由这些变量控制：

VITE_HTTP_PROXY=Y
VITE_PROXY_LOG=Y

@skyroc/web-admin-vite 会在 dev server 下创建：

生产部署不要依赖 Vite dev proxy。生产包里的接口地址来自构建时的 env：

VITE_SERVICE_BASE_URL=https://api.example.com
VITE_OTHER_SERVICE_BASE_URL={ demo: "https://demo-api.example.com" }

如果线上需要通过同域 Nginx 转发后端，可以把 VITE_SERVICE_BASE_URL 配成同域路径，再在 Nginx 增加 API location：

VITE_SERVICE_BASE_URL=/api

location /api/ {
  proxy_pass https://api.example.com/;
}

注意路径重写规则要和后端接口路径对齐，避免 /api/auth/login 被转发成错误路径。

构建产物规则

@skyroc/web-admin-vite 默认会调整 Rollup 输出：

需要增加 manual chunks 时，不要完全重写 Vite 配置，优先通过 application.build.manualChunks 扩展：

import { defineConfig } from '@skyroc/web-admin-vite';

export default defineConfig({
  application: {
    build: {
      manualChunks: {
        charts: ['echarts']
      }
    }
  }
});

CI 示例

一个最小 CI 构建流程可以是：

corepack enable
corepack prepare pnpm@10.4.1 --activate
pnpm install --frozen-lockfile
pnpm --filter skyroc-admin typecheck
pnpm --filter skyroc-admin build

如果 CI 只做静态部署，上传 apps/admin/dist 即可。实际目录以 Vite build 输出为准。

常见问题

相关链接

• 快速开始：快速开始
• 环境变量与 Vite：环境变量与 Vite
• 路由守卫和 history 路由刷新：路由守卫