# uni-app 3 端

本文介绍基于 uni-app 3 + Vue 3 + Vite + TypeScript 的移动端模块(源码目录 resources/uniapp3)。

基于 Vue 2 的旧版移动端(目录 resources/mobile)见 uni-app 端,两者目录、配置与构建脚本不通用。

# 前端代码位置

源代码位于 module/XxxMobile/resources/uniapp3:

目录 说明
src/pages/ 业务页面(新增后到 src/pages.json 登记路由)
src/brick/ 移动端基础库(接口、路由、组件、会员页面、系统页面),升级时整体替换,不要改业务以外的东西
src/config/ setting.ts(接口地址 / 免登录页面 / tabBar)、bootstrap.ts(启动数据)、token.less + tokens.ts(设计令牌)
src/icons/lucide/ Lucide 图标生成物(vite-plugin-uni-icons.js 构建时自动对齐)
src/static/ tabBar 图标、空状态图等静态资源
src/manifest.json 应用标识、包名、图标、权限
src/pages.json 页面路由、tabBar、easycom 规则
module-build.cjs 构建脚本(H5 构建 + ModStart 集成)
module-dev.cjs H5 开发服务脚本

编译后的静态资源写入 module/XxxMobile/Asset,H5 入口模板写入 module/XxxMobile/View/m/xxxMobile;模块安装时自动复制到 public/vendor/XxxMobile,页面通过 /vendor/XxxMobile/xxx.js 引用。

# 与 uni-app 2 的区别

项目 uni-app 2(resources/mobile) uni-app 3(resources/uniapp3)
Vue 版本 Vue 2(Options API) Vue 3(script setup + TypeScript)
构建工具 vue-cli Vite
Node 版本 14 以目录下 .nvmrc 为准(模板为 24)
应用配置 src/config/setting.js src/config/setting.ts + src/config/bootstrap.ts
状态管理 Vuex Pinia
主题样式 src/config/theme.less 的 @color-primary src/config/token.less + src/config/tokens.ts 的 --token-*
图标 字体图标 / 图片 icon-lucide-* 组件(构建时由图标插件生成)
产物目录 Asset/static 等 Asset/**(整目录重建)

# 创建移动端模块

后台「系统管理」→「模块开发助手」→ 创建模块 → Uniapp3移动端模块,填写标识(如 Shop)与名称,系统会生成 module/ShopMobile,源码位于 module/ShopMobile/resources/uniapp3。

# 环境准备

  • Node.js:版本以 resources/uniapp3/.nvmrc 为准(模板为 24),版本不符时构建会直接失败。
  • H5 / 小程序:命令行即可完成构建,不强制安装 HBuilderX。
  • App 云打包、小程序真机调试:需要 HBuilderX、微信开发者工具 (opens new window)。

# 构建与开发

进入源码目录执行(脚本按所在目录推断模块名与产物路径,不能从其他目录调用):

cd module/XxxMobile/resources/uniapp3
nvm use "$(cat .nvmrc)"                  # 或自行安装 .nvmrc 指定版本的 Node

# H5:构建 + ModStart 集成(写入 module/XxxMobile/Asset 与 View/m/xxxMobile)
node module-build.cjs
node module-build.cjs --env test          # 指定 Vite mode(.env.test / .env.test.local)
node module-build.cjs --skip-install      # 依赖已装好时跳过 npm install

# 其他平台只构建,不写入模块产物
node module-build.cjs mp-weixin
node module-build.cjs apk                 # 等价 app-plus

# H5 开发服务(端口取 src/manifest.json 的 h5.devServer.port)
node module-dev.cjs
node module-dev.cjs --env test --port 21001 --host 0.0.0.0
node module-dev.cjs --proxy http://127.0.0.1:8000   # 仅本次运行覆盖接口代理地址
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

构建完成后,把 module/XxxMobile/Asset、module/XxxMobile/View/m/xxxMobile 更新到服务器,并在服务器执行:

php artisan modstart:module-install XxxMobile --force
1

module-build.cjs 会用 BUILD_TARGET=publish-pro 注入占位 base 并统一替换路径:Blade 内替换为 AssetsUtil::cdn() 表达式,JS 内替换为 window.__msCDN 拼接,CSS 内改为相对路径。Asset/ 是整目录重建,不要手工修改。

dist/、node_modules/ 不入库,入库产物只有 Asset/** 与 View/m/**。

# 应用配置

# 接口地址与页面配置

文件 src/config/setting.ts:

  • apiBase:H5 使用页面注入的 window.__msApi(由 Blade 入口写入,未注入时为 /api/);非 H5(小程序 / App)读取 VITE_API_BASE,未设置时使用当前站点域名。
  • route.home / route.login / route.tabBar:首页、登录页、tabBar 页面。
  • route.authIgnores:免登录即可访问的页面列表。

开发时的接口代理地址通过 .env.development.local 的 VITE_PROXY_TARGET 或 node module-dev.cjs --proxy <地址> 指定。

# 启动数据

文件 src/config/bootstrap.ts:应用启动时请求 模块标识/config(站点配置)与 模块标识/config_app(用户与业务数据),模块标识与后端 Api/routes.php 保持一致。

# 页面路由

文件 src/pages.json:新增页面后必须在此登记,否则无法跳转;tabBar 图标的图片需同时放在 src/static/ 下。

# 修改移动端主色调

  • 颜色令牌:src/config/token.less(CSS 变量 --token-*)与 src/config/tokens.ts(TS 常量)必须同步修改,页面样式统一引用令牌,不要硬编码颜色。
  • 图标颜色:<icon-lucide-check color="var(--token-action-text)" />,小程序端图标由插件换算为具体色值。
  • 图片资源:src/static/,图标不要使用字体图标或外链 CDN。

# 打包微信小程序

cd module/XxxMobile/resources/uniapp3
node module-build.cjs mp-weixin
1
2

用微信开发者工具打开 module/XxxMobile/resources/uniapp3/dist/build/mp-weixin/ 预览并上传。

# 打包 App(Android / iOS)

  1. 用 HBuilderX 打开目录 module/XxxMobile/resources/uniapp3;
  2. 打开 src/manifest.json 重新获取应用标识,并填写 Android 包名 / iOS Bundle ID、应用图标;
  3. 发行 → App 原生云打包,完成后下载安装包。

# 常见问题

# 构建报 Node 版本不支持

先执行 nvm use "$(cat .nvmrc)",使用该目录指定的 Node 版本(旧版本 Node 无法运行 Vite 构建)。

# 构建提示图标不存在

图标名取自 Lucide 图标集(kebab-case)。图标改名后旧名会作为别名保留,插件仍可正确生成;若提示某个图标名不存在,请改用 iconify 中存在的名称(可用 node vite-plugin-uni-icons.js --check 校验)。

# 改了源码页面没有变化

只改 src/ 不会生效,必须重新执行 node module-build.cjs 并 php artisan modstart:module-install XxxMobile --force 发布产物。

# 打包后图片 / 样式丢失

检查是否手工修改过 Asset/(该目录由构建整目录重建),以及图片是否放在 src/static/ 下而非外部链接。

Last Updated: 20 hours ago