# 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 # 仅本次运行覆盖接口代理地址
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
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
2
用微信开发者工具打开 module/XxxMobile/resources/uniapp3/dist/build/mp-weixin/ 预览并上传。
# 打包 App(Android / iOS)
- 用 HBuilderX 打开目录
module/XxxMobile/resources/uniapp3; - 打开
src/manifest.json重新获取应用标识,并填写 Android 包名 / iOS Bundle ID、应用图标; - 发行 → 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/ 下而非外部链接。