跳到主要内容

部署 PC 前端

本文介绍 ShopTNT 开源版 8.0 的静态文件部署方式:在构建机编译买家 PC 端、商家管理端和平台管理端,再把产物发布到服务器的 Nginx 站点目录。三个应用可使用独立域名,也可部署到同一域名的不同路径。

构建机需要 Node.js 和 pnpm;只提供静态文件的部署服务器需要 Nginx,无需启动前端开发服务。使用 Docker 部署时,请参考构建 UI 镜像。移动端使用独立工程,见部署移动端。

1. 准备环境和源码​

推荐使用 Node.js 22.17.0 及以上的 Node.js 22 版本。PC 工程使用 pnpm@11.7.0,以根目录的 packageManager 为准。

node --version
corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm --version

git clone --branch 8.0 https://gitee.com/bbc-se/pc-ui.git
cd pc-ui
git branch --show-current
git rev-parse HEAD

已有源码时,直接进入对应的 8.0 工程根目录。后续构建命令都在该目录执行,并记录本次提交哈希,便于追溯发布版本。

2. 配置生产环境​

生产构建读取根目录 .env.production,并可能受到 .env.local、.env.production.local 和当前进程环境变量的覆盖。先检查这些配置,避免把开发机的私有地址带入生产产物。

API 地址和站点域名​

将 .env.production 中的演示地址替换成实际地址。以下示例使用四个独立 API 地址和三个独立站点域名:

VITE_API_GATEWAY=
VITE_API_BASE=https://base-api.example.com
VITE_API_BUYER=https://buyer-api.example.com
VITE_API_SELLER=https://seller-api.example.com
VITE_API_ADMIN=https://admin-api.example.com

VITE_DOMAIN_PC=https://www.example.com
VITE_DOMAIN_SELLER=https://seller.example.com
VITE_DOMAIN_ADMIN=https://admin.example.com
VITE_DOMAIN_MOBILE=https://m.example.com

VITE_BASE_PC=
VITE_BASE_SELLER=
VITE_BASE_ADMIN=

VITE_ASSETS_PC=
VITE_ASSETS_SELLER=
VITE_ASSETS_ADMIN=

API 必须能从用户浏览器访问;跨域 API 需要后端或网关允许对应站点的请求。未部署移动 H5 时,将 VITE_DOMAIN_MOBILE 留空。功能开关按实际业务调整,完整变量说明见配置文件详解。VITE_* 会进入浏览器产物,只能填写公开配置。

如果后端通过同一个网关承载全部 API,将上面的五个 API 配置改为:

VITE_API_GATEWAY=https://api.example.com
VITE_API_BASE=
VITE_API_BUYER=
VITE_API_SELLER=
VITE_API_ADMIN=

普通静态构建中,非空的分端 API 地址优先于统一网关。工程自带的生产配置已有分端地址,因此切换到统一网关时需要同时清空它们。使用 /api 等同源地址时,还必须在 Web 服务器配置对应的反向代理,静态页面服务本身不会自动代理后端。

同域名子路径​

如果三个应用分别部署到 https://www.example.com/、https://www.example.com/seller/ 和 https://www.example.com/admin/,构建前还需调整:

VITE_DOMAIN_PC=https://www.example.com
VITE_DOMAIN_SELLER=https://www.example.com/seller
VITE_DOMAIN_ADMIN=https://www.example.com/admin

VITE_BASE_PC=
VITE_BASE_SELLER=seller
VITE_BASE_ADMIN=admin

VITE_DOMAIN_* 用于跨端链接,VITE_BASE_* 决定资源地址和路由前缀,两者需要与实际访问地址一致。改变部署路径后需要重新构建,不能只移动原有产物目录。不使用 CDN 时,保持 VITE_ASSETS_* 为空。

3. 安装依赖并构建​

以下命令在子 Shell 中执行,任一步失败都会停止本次检查和构建:

(
set -eu
test "$(pnpm --version)" = "11.7.0"
pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm locale:check
pnpm build

for app in pc seller admin; do
for file in index.html runtime-config.js version; do
test -s "apps/$app/dist/$file"
done
test -d "apps/$app/dist/assets"
done
)

pnpm build 使用 production 模式构建全部三端,分别输出到:

应用产物目录
买家 PC 端apps/pc/dist
商家管理端apps/seller/dist
平台管理端apps/admin/dist

只更新单个应用时,可在完成相关检查后使用 pnpm build:pc、pnpm build:seller 或 pnpm build:admin。构建命令非零退出或产物缺失时,先解决问题再发布。

4. 发布完整静态产物​

将对应 dist 目录内的全部内容上传到目标站点目录。每一端的 index.html、runtime-config.js、version、assets/ 及其他随包资源必须来自同一次构建。

runtime-config.js 在应用模块之前加载。普通静态构建生成的是空配置脚本,应用继续使用构建时的环境配置;即使不使用运行时覆盖,这个脚本也必须发布。Nginx 不会自动把系统环境变量写入前端,修改 .env.production 后需要重新构建、发布。

可按发布批次保留完整产物,再由发布工具或站点目录切换当前版本。独立域名部署的目录示例:

/var/www/shop-tnt/releases/<发布批次>/
├── pc/
│ ├── index.html
│ ├── runtime-config.js
│ ├── version
│ └── assets/
├── seller/
└── admin/

/var/www/shop-tnt/current -> /var/www/shop-tnt/releases/<发布批次>

pc/、seller/、admin/ 分别保存对应 dist 的内容。以上路径可按服务器调整;不要上传源码、环境配置文件、node_modules 或 .git。站点目录和文件需要允许 Nginx 工作进程读取,公开静态目录和文件通常分别使用 0755、0644。

5. 配置 Nginx​

以下 server 示例放入 Nginx 的 http 配置中,并确认 http 层已加载 mime.types,使 JavaScript、CSS 等文件返回正确的内容类型。示例展示 HTTP 静态服务;正式站点的 HTTPS 证书或外层代理应与生产配置中的站点地址一致。

独立域名​

下面以商家端为例,站点根目录指向商家端的完整产物:

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

root /var/www/shop-tnt/current/seller;
index index.html;

location ~ ^/(runtime-config\.js|version)$ {
add_header Cache-Control "no-store" always;
try_files $uri =404;
}

location = /index.html {
add_header Cache-Control "no-cache" always;
try_files $uri =404;
}

location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
try_files $uri =404;
}

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

买家 PC 和平台管理端各增加一个 server,分别使用 www.example.com、admin.example.com,将 root 指向 current/pc、current/admin。

同域名子路径​

先按第 2 步配置子路径并重新构建,再准备组合站点目录:

/var/www/shop-tnt/current/webroot/
├── index.html # 买家 PC 端 dist 的内容
├── runtime-config.js
├── version
├── assets/
├── seller/ # 商家端 dist 的全部内容
└── admin/ # 管理端 dist 的全部内容

将组合站点设为 Nginx 的根目录:

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

root /var/www/shop-tnt/current/webroot;
index index.html;

location ~ ^/(seller/|admin/)?(runtime-config\.js|version)$ {
add_header Cache-Control "no-store" always;
try_files $uri =404;
}

location ~ ^/(seller/|admin/)?index\.html$ {
add_header Cache-Control "no-cache" always;
try_files $uri =404;
}

location ~ ^/(seller/|admin/)?assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
try_files $uri =404;
}

location = /seller {
return 301 /seller/;
}

location = /admin {
return 301 /admin/;
}

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

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

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

这些规则让二级页面回退到各自的 HTML,同时让缺失的配置、版本文件和 assets/ 资源返回 404,避免把 HTML 当成 JavaScript 返回。配置与版本文件禁止缓存,HTML 每次重新验证,带哈希的静态资源可长期缓存。

修改配置后先执行:

nginx -t

检查成功后,按服务器当前的服务管理方式重载 Nginx。

6. 上线验证与回滚​

按实际域名和前缀检查入口、配置脚本和版本文件。独立域名的商家端示例:

curl -fsSI https://seller.example.com/index.html
curl -fsSI https://seller.example.com/runtime-config.js
curl -fsS https://seller.example.com/runtime-config.js
curl -fsSI https://seller.example.com/version

确认配置请求返回 HTTP 200 和 JavaScript 内容,而不是 HTML;普通静态构建的脚本内容为 globalThis.__SHOP_TNT_RUNTIME_CONFIG__ = {};。同域名子路径部署时,对应地址应是 /seller/runtime-config.js 和 /seller/version。

再逐端检查:

  1. 首页、登录页和二级页面直接打开、刷新均正常。
  2. 首页引用的 JS、CSS、字体和图片正常加载;缺失资源应返回 404。
  3. API 和跨端跳转指向实际环境,没有 CORS、Mixed Content 或连续 401。
  4. 登录、退出、上传、后台权限菜单和关键业务流程正常。
  5. runtime-config.js、version 返回 Cache-Control: no-store,HTML 不使用长期缓存。

构建通过只说明静态产物已生成,业务访问仍需实际验证。回滚时切换到上一批完整产物,保留同一批次的 HTML、配置、版本和资源文件,再执行相同的访问检查。