跳到主要内容

部署移动端

本页以开源 mobile-ui 的 8.0 分支为准,介绍 H5 移动商城的生产构建和 Nginx 手动部署,并说明微信小程序、App 的发布流程。示例域名均需替换为自己的实际域名。

准备环境与源码​

构建机安装 Git、Node.js 和 npm。当前源码要求 Node.js 20.15.0 及以上的 20.x,或 22.17.0 及以上的 22.x,建议使用符合范围的 22.x。H5 静态文件服务器只需 Nginx,无须安装 Node.js 或 HBuilderX。

node -v
npm -v
git clone --branch 8.0 --single-branch https://gitee.com/bbc-se/mobile-ui.git
cd mobile-ui
npm install --legacy-peer-deps --include=dev --no-package-lock

当前仓库没有根目录依赖锁文件,以上安装方式与项目构建脚本一致;若后续版本提供 package-lock.json,使用 npm ci --legacy-peer-deps --include=dev。构建依赖位于 devDependencies,安装时需包含它们。

部署前准备:

  • 后端 API 已部署,并通过 HTTPS 对外提供服务,例如基础 API https://base-api.example.com、买家 API https://buyer-api.example.com。
  • H5 域名 m.example.com 已解析至 Web 服务器,并准备好该域名的 HTTPS 证书。
  • API 服务或网关允许移动站点 https://m.example.com 的跨域请求;若使用统一网关,以实际网关地址和路由为准。

配置生产环境​

配置文件是 src/config/config.js。保持 environmentOverride.enabled: false,让环境选择跟随构建命令;分别修改 api 和 domain 对象中的 pro 配置:

配置项示例值用途
api.pro.basehttps://base-api.example.com基础业务 API 根地址
api.pro.buyerhttps://buyer-api.example.com买家 API 根地址
domain.pro.waphttps://m.example.comH5 站点根地址,用于分享、授权及支付回跳等
domain.pro.sellerhttps://seller.example.com实际商家站点根地址

API 地址填写部署后的服务根地址或网关前缀,具体接口路径由程序拼接。例如基础 API 会请求 ${api.base}/base/site-show,不要在根地址中重复添加接口的 /base 路径。站点地址使用 HTTPS 域名根地址,不加 /h5/ 等子路径,也不要保留源码中的演示域名。

上述配置同时用于 H5、小程序和 App。src/manifest.json 中 H5 路由当前为 history 模式,base 为空,本页按站点根路径 / 部署。若需要部署到子目录,须同时调整路由、资源路径和业务跳转后重新构建,不能只改 Nginx 的目录映射。

构建 H5 生产包​

在项目根目录执行:

VUE_APP_ENV_MODE=production npm run build:h5

Windows PowerShell 使用:

$env:VUE_APP_ENV_MODE = 'production'
npm run build:h5

直接执行 npm run build:h5 或 npm run build 默认生成测试环境产物。 脚本虽然设置了 NODE_ENV=production,仍会默认选择 VUE_APP_ENV_MODE=test;部署生产环境必须显式传入 VUE_APP_ENV_MODE=production。构建结束时确认日志显示环境为 production,且命令成功退出。

产物输出至 dist/build/h5/,其中应包含非空的 index.html、runtime-config.js 及全部 JS、CSS、图片等资源。可在构建机检查并归档:

test -s dist/build/h5/index.html
test -s dist/build/h5/runtime-config.js
tar -czf mobile-h5.tar.gz -C dist/build/h5 .

H5 运行时配置​

普通静态构建生成的 runtime-config.js 内容为:

window.__SHOP_TNT_RUNTIME_CONFIG__ = {};

保留此文件时,H5 使用前面写入源码的生产配置。若要在发布时覆盖 H5 的 API 和站点地址,可以在归档前将 dist/build/h5/runtime-config.js 改为:

window.__SHOP_TNT_RUNTIME_CONFIG__ = {
VITE_API_BASE: "https://base-api.example.com",
VITE_API_BUYER: "https://buyer-api.example.com",
VITE_DOMAIN_MOBILE: "https://m.example.com",
VITE_DOMAIN_SELLER: "https://seller.example.com",
};

修改运行时配置后,重新执行前面的归档命令,再上传发布。

统一网关也可通过 VITE_API_GATEWAY 同时指定基础和买家 API;单独配置的 VITE_API_BASE、VITE_API_BUYER 优先级更高。API 可用完整 HTTP(S) 地址或 /api 这样的同源前缀;使用同源前缀时,需另外配置对应的反向代理。下方 Nginx 示例仅提供静态文件服务。

运行时文件会在应用脚本之前同步加载,丢失、返回 HTML 或配置无效都会导致初始化失败,空对象配置文件也必须随产物一起发布。这些字段是浏览器可见的公开地址,不填写密钥。静态部署只修改服务器环境变量不会自动更新此文件;需要更新文件并刷新页面。它只覆盖 H5 的 API 和站点地址,不会切换构建环境、功能开关或小程序/App 的配置。

发布 H5 到 Nginx​

上传完整产物​

将归档文件上传到 Web 服务器,以下用户名和服务器地址按实际情况替换:

scp mobile-h5.tar.gz deploy@web.example.com:/tmp/

登录 Web 服务器后执行:

sudo mkdir -p /var/www/shoptnt/mobile
sudo tar -xzf /tmp/mobile-h5.tar.gz -C /var/www/shoptnt/mobile

解压后应直接存在 /var/www/shoptnt/mobile/index.html 和 /var/www/shoptnt/mobile/runtime-config.js,Nginx 工作进程需有权读取整个目录。上传的是 dist/build/h5/ 内的完整内容,不要只上传入口文件,或在站点根目录下再嵌套一层 h5。

后续更新先备份上一版完整产物和配置,建议将新版本发布至独立目录,再切换站点目录,避免用户同时读取到两版文件。若使用自定义运行时配置,每次发布都需重新写入该配置,防止新构建的空配置覆盖实际地址。

配置站点与缓存​

将下列 server 配置加入 Nginx 的 http 配置范围内,例如站点配置目录中。替换域名、站点目录和证书路径,确保主配置已加载 MIME 类型配置。

server {
listen 80;
server_name m.example.com;
return 301 https://$host$request_uri;
}

server {
listen 443 ssl;
server_name m.example.com;

ssl_certificate /etc/nginx/certs/m.example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/m.example.com/privkey.pem;

root /var/www/shoptnt/mobile;
index index.html;

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

location = /runtime-config.js {
add_header Cache-Control "no-store" always;
try_files $uri =404;
}

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

location ~* \.(?:js|css|json|map|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|otf|eot|mp4|mp3)$ {
add_header Cache-Control "no-cache" always;
try_files $uri =404;
}

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

history 路由需要将普通页面请求回退到 index.html,否则直接访问或刷新商品、订单等页面会出现 404。静态资源和 runtime-config.js 缺失时则必须返回 404,不能回退成 HTML。

入口 HTML 与运行时配置使用 no-store,避免更新后继续使用旧入口或旧地址。示例对其他资源使用 no-cache,允许保存副本但每次使用前重新验证;不要对所有 JS、CSS、图片统一设置长期 immutable 缓存,产物中可能包含文件名固定的资源。若使用 CDN,也需保持相同的入口与配置缓存策略。

检查配置并平滑加载:

sudo nginx -t
sudo nginx -s reload

上线验证​

curl -I https://m.example.com/
curl -I https://m.example.com/index.html
curl -I https://m.example.com/runtime-config.js
curl -I https://m.example.com/pages/tabs/home/home
curl -I https://m.example.com/static/__missing__.js

首页与已有页面的直达地址应返回 HTML;入口和配置响应应带 Cache-Control: no-store。运行时配置应返回 JavaScript,最后一条不存在的资源请求应返回 404。

在手机浏览器访问站点,检查首页、商品详情和页面刷新;在浏览器网络面板确认 API 已指向自己的生产域名、JS/CSS 没有收到 HTML 响应,再验证登录、购物车、下单、支付回跳和图片上传。使用微信内 H5 登录或支付时,还需将公众号网页授权域名、JS 接口安全域名及支付授权目录与实际 H5 地址对应配置。

微信小程序发布​

微信小程序需要独立构建,H5 产物不能用于小程序发布。

  1. 在 src/manifest.json 的 mp-weixin.appid 中填写自己的真实微信小程序 AppID,并同步替换仓库根目录 project.config.json 中的 appid。确认生产 API 和站点地址已经按前文配置。

  2. 在微信小程序后台配置实际使用的 HTTPS 合法域名:API 请求对应 request,图片或文件上传对应 uploadFile,图片或文件下载对应 downloadFile,IM 等 WebSocket 连接对应 socket(使用 WSS)。若页面使用 web-view,还需配置业务域名。

  3. 执行生产构建:

    VUE_APP_ENV_MODE=production npm run build:mp-weixin

    PowerShell 可先按前文设置 $env:VUE_APP_ENV_MODE = 'production',再执行 npm run build:mp-weixin。该脚本默认就是生产环境,此处显式指定以避免继承终端中的测试环境变量。

  4. 成功产物位于 dist/build/mp-weixin/。脚本会检查关键文件、产物内的实际配置以及主包和各分包体积;构建失败时先解决输出的错误。

  5. 使用微信开发者工具导入 dist/build/mp-weixin/,核对产物 project.config.json 的 AppID 与自己的小程序一致。在开启域名校验的条件下进行真机预览,验证微信登录、支付、上传和下载,再通过开发者工具上传版本,在微信小程序后台提交审核并发布。

源码中的 mp-weixin.setting.urlCheck 当前为 false,这只是调试设置;正式发布仍需真实 AppID 和已配置的合法域名,不能依赖关闭域名校验。涉及微信登录和支付时,后端对应的小程序 AppID、登录配置及支付商户配置也需与该小程序一致。

App 打包与发布​

App 使用独立的原生打包流程。项目提供以下生产编译命令:

VUE_APP_ENV_MODE=production npm run build:app-plus

PowerShell 设置生产环境变量后执行 npm run build:app-plus。此命令编译 App 资源,不直接生成可分发的 Android APK/AAB 或 iOS IPA,也不完成签名和应用商店发布。

需要发布 App 时,使用与项目 uni-app 编译依赖匹配的 HBuilderX及对应原生打包环境。按 DCloud App 打包文档完成后续操作:

  1. 在 src/manifest.json 中配置自己的 DCloud AppID、应用名称、版本,以及实际使用的登录、支付、分享等原生模块参数。DCloud AppID 与微信小程序 AppID 分别对应各自平台。
  2. 准备 Android 应用包名、签名证书;iOS 准备 Bundle ID、发行证书和描述文件,并选择支持目标平台的打包方式。微信等平台的 AppID、包名、签名或 Universal Links 也需与实际应用一致。
  3. 完成原生打包后在真机验证生产 API、登录、下单和支付回跳,再按分发渠道或应用商店要求发布。

生产 API 和站点地址来自构建时的 src/config/config.js;H5 的 runtime-config.js 不作用于 App。手机 USB 调试和“运行到手机”仅用于开发验证,不能代替签名打包与正式发布。