07.2.4.2 工程形态与配置体系
所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.2 跨平台移动开发 / 07.2.4 uni-app
本节要解决的问题
- HBuilderX 工程与 CLI 工程到底差在哪,团队协作与 CI 场景该选哪个?
- Vue2 + webpack 与 Vue3 + Vite 两条编译链在配置、速度、生态上有哪些差异?
- uni-app 工程的目录约定(pages、static、components、uni_modules)各自职责是什么?
- pages.json 如何注册页面、配置 tabBar、分包、启动页与条件编译?
- manifest.json 的 appid、权限、模块、各端差异化配置怎么写?
- easycom 自动引入的规则与边界是什么,为什么要避免过度依赖?
- vite/webpack 配置、alias、uni_modules 与 npm 依赖、环境变量、TypeScript 怎么组织?
版本前提:本页以 Vue3 + Vite 链为主线,Vue2 + webpack 链作为对照;具体字段名、默认值、构建命令以官方文档(uniapp.dcloud.net.cn/collocation/)为准,标注待确认处需按项目实际版本核对。
覆盖范围
| 知识域 | 关键内容 |
|---|---|
| 工程形态 | HBuilderX 工程 vs CLI 工程、vue-cli vs Vite 模板 |
| 目录约定 | pages/static/components/uni_modules/platforms |
| pages.json | 页面注册、启动页、tabBar、globalStyle、分包、条件编译 |
| manifest.json | appid、版本、App 权限与模块、小程序 appid、H5 路由 |
| 构建配置 | easycom、vite/webpack alias、uni_modules 与 npm、环境变量、TS |
| 综合场景 | 新项目选型、pages.json 配置排查 |
题号索引
| 题号区间 | 主题 |
|---|---|
| 001-002 | 工程形态(HBuilderX vs CLI)、两条编译链 |
| 003-004 | 目录约定、入口文件 |
| 005-008 | pages.json:页面、启动页、tabBar、globalStyle、分包、条件编译 |
| 009-011 | manifest.json:基础信息、App 权限模块、小程序 appid、H5 路由 |
| 012-014 | easycom、vite/webpack alias、uni_modules 与 npm |
| 015-016 | 环境变量与多环境、TypeScript |
| 017-018 | 综合:新项目工程选型、pages.json 排查 |
07.2.4.2-001 HBuilderX 工程与 CLI 工程有什么差异?
一句话结论
HBuilderX 工程是 DCloud 官方 IDE 管理的工程形态,内置工程创建、运行、云打包、插件市场下载;CLI 工程基于 npm 包(vue-cli 或 Vite 模板),可在任意编辑器开发,便于 CI 与团队协作。两者产出的源码结构一致,差异在工程管理与构建入口。
概念解释
HBuilderX 工程的特点是"开箱即用":新建项目时选择模板(默认 Vue3/Vue2),IDE 自动生成 pages.json、manifest.json、App.vue、main.js,运行到各端是 IDE 菜单操作,云打包、真机运行、插件市场下载都集成在 IDE 里。代价是工程依赖 IDE 管理,CI 场景需要把工程目录推到服务器再用 CLI 命令构建,团队成员必须装 HBuilderX。
CLI 工程的特点是"标准 npm 工程":通过 npx degit dcloudio/uni-preset-vue#vite(具体命令以官方为准)拉取模板,用 npm run dev:h5、npm run build:app 等脚本运行,编辑器任选,CI 友好。代价是需要自己配证书、云打包命令、真机运行链路。
原理流程
HBuilderX 工程:
IDE 新建项目 → 菜单运行/打包 → 云打包/本地运行
CLI 工程:
npx degit 模板 → npm install → npm run dev:xxx → CI 构建
代码或图示
| 维度 | HBuilderX 工程 | CLI 工程 |
|---|---|---|
| 创建方式 | IDE 菜单 | npx degit / 模板 |
| 编辑器 | HBuilderX | 任意 |
| 运行 | IDE 菜单 | npm run 脚本 |
| 云打包 | IDE 内置 | CLI 命令或本地打包 |
| CI | 需适配 | 原生友好 |
| 团队协作 | 成员需装 HBuilderX | 标准 npm 流程 |
| 插件市场 | IDE 一键下载 | 手动拷贝或命令 |
常见误区
- 误区:HBuilderX 工程和 CLI 工程源码结构不同;正解:两者都是标准 uni-app 工程,pages.json/manifest.json 位置一致,可互相转换。
- 误区:CLI 工程不能用插件市场;正解:uni_modules 插件可手动拷贝到 uni_modules/ 目录,与 HBuilderX 下载效果一致。
追问
- Q:团队协作选哪个?A:推荐 CLI,编辑器自由、CI 友好、版本管理标准;HBuilderX 适合个人开发者或快速原型。
- Q:HBuilderX 工程能转 CLI 吗?A:可以,工程目录本身就是标准结构,补 package.json 与构建脚本即可。
07.2.4.2-002 Vue2 + webpack 与 Vue3 + Vite 两条编译链有什么差异?
一句话结论
Vue2 链用 webpack(vue-cli 模板),构建慢、HMR 慢、TS 支持弱;Vue3 链用 Vite,基于 ESM 的启动与 HMR 快,原生支持 TS 与 Composition API。新项目一律选 Vue3 + Vite,存量项目按插件依赖决定是否迁移。
概念解释
webpack 是打包器,启动时把整个工程打成 bundle,工程越大启动越慢;Vite 在开发时利用浏览器原生 ESM,只编译当前页面用到的模块,启动几乎即时,HMR 只更新改动模块。生产构建时 Vite 用 Rollup 打包,产物体积与 webpack 相当。
运行时差异:Vue2 用 defineProperty 响应式,Vue3 用 Proxy;Vue3 原生支持 <script setup> 与 TS 类型推导。生态差异:Vue2 链的插件市场老插件多,Vue3 链需逐个确认兼容。配置文件差异:Vue2 链在 vue.config.js 或 package.json 配 webpack,Vue3 链在 vite.config.ts 配 Vite 与 uni 插件。
原理流程
Vue2 + webpack:.vue → vue-loader → webpack bundle → 各端产物
Vue3 + Vite:.vue → @vitejs/plugin-vue → Vite dev server(ESM)→ 生产用 Rollup
代码或图示
| 维度 | Vue2 + webpack | Vue3 + Vite |
|---|---|---|
| 构建工具 | webpack | Vite(dev)+ Rollup(prod) |
| 启动速度 | 慢,随工程增长 | 快,ESM 按需 |
| HMR | 整包重编译 | 模块级热更新 |
| 响应式 | defineProperty | Proxy |
| Composition API | 需插件 | 原生 |
| TypeScript | 弱 | 原生 |
| 配置文件 | vue.config.js | vite.config.ts |
| 生态 | 老插件多 | 需逐个确认 Vue3 版 |
常见误区
- 误区:Vite 生产构建也快;正解:生产用 Rollup 打包,速度与 webpack 相当,Vite 的优势在开发时。
- 误区:Vue3 链不支持 webpack;正解:Vue3 链主推 Vite,但也存在 webpack 版本,具体以官方模板为准。
追问
- Q:Vite 的 alias 怎么配?A:在 vite.config.ts 的 resolve.alias 中配置,与普通 Vite 工程一致。
- Q:Vue3 链的小程序产物和 Vue2 链一样吗?A:产物都是标准小程序工程,运行时与框架版本不同,需真机回归。
07.2.4.2-003 uni-app 工程的目录约定是什么?
一句话结论
标准 uni-app 工程根目录包含:pages/(页面)、static/(静态资源)、components/(公共组件)、uni_modules/(插件)、App.vue(应用入口)、main.js(运行入口)、pages.json(页面路由配置)、manifest.json(应用配置);可选目录有 static 之外的资源目录与 platform 特定目录。
概念解释
pages/ 是页面目录,每个页面一个子目录,内含 index.vue 与对应配置(通过 pages.json 注册,不在文件内路由)。static/ 是不参与编译的静态资源目录,图片、字体、JSON 等放这里,引用时用绝对路径 /static/xx.png;components/ 是公共 Vue 组件,可通过 easycom 自动引入。uni_modules/ 是 DCloud 插件市场的模块目录,每个插件一个子目录。
App.vue 是应用组件(不含模板,只做全局生命周期与全局样式),main.js 是 Vue 运行入口(createApp),pages.json 是路由与窗口配置的"单一来源",manifest.json 是应用元信息与各端配置。
原理流程
项目根/
├── pages/ # 页面(按目录组织)
│ └── index/index.vue
├── static/ # 不编译的静态资源
├── components/ # 公共组件(easycom)
├── uni_modules/ # 插件市场模块
├── App.vue # 应用入口(生命周期 + 全局样式)
├── main.js # 运行入口
├── pages.json # 页面路由与窗口
└── manifest.json # 应用配置
代码或图示
| 目录 | 职责 | 是否参与编译 |
|---|---|---|
| pages/ | 页面 | 是 |
| static/ | 静态资源 | 否,原样拷贝 |
| components/ | 公共组件 | 是(按需引入或 easycom) |
| uni_modules/ | 插件 | 是(按需) |
| App.vue | 全局生命周期与样式 | 是 |
| main.js | 运行入口 | 是 |
常见误区
- 误区:static/ 里的资源会被 webpack/Vite 压缩;正解:static/ 原样拷贝,不参与编译与压缩。
- 误区:页面路由写在 vue 文件里;正解:页面必须在 pages.json 注册,文件内不写路由。
追问
- Q:图片放 static/ 还是 assets/?A:uni-app 没有 assets/ 约定,图片一律放 static/,用
/static/xx.png引用;组件内 import 的图片由构建处理。 - Q:平台特定代码放哪?A:用条件编译(见 07.2.4.3),不需要平台特定目录;个别端配置放 manifest.json 的对应节。
07.2.4.2-004 App.vue 与 main.js 各自承担什么?
一句话结论
main.js 是 Vue 应用运行入口(createApp、挂载全局插件),App.vue 是应用级组件(不渲染模板,只定义应用生命周期 onLaunch/onShow/onHide 与全局样式);两者职责不同,不要把业务逻辑放错位置。
概念解释
main.js 里做 createApp(App),挂载全局插件(Pinia、router 插件等)、全局指令、全局混入。App.vue 里写 <script> 块定义应用生命周期:onLaunch(启动)、onShow(前台)、onHide(后台);<style> 块写全局样式。App.vue 不写 <template>,它不是页面。
常见错误是把页面级逻辑写到 App.vue 的 onLaunch 里假设"只执行一次",实际上 onLaunch 在冷启动时执行,热更新与小程序场景时机不同;业务初始化应在首页面 onLoad 或 Pinia action 里做。
原理流程
main.js:
import { createApp } from 'vue'
import App from './App.vue'
createApp(App).use(pinia).mount('#app') // mount 目标随端变化
App.vue:
<script setup>
onLaunch(() => { /* 启动 */ })
onShow(() => { /* 前台 */ })
onHide(() => { /* 后台 */ })
</script>
<style>/* 全局样式 */</style>
代码或图示
| 文件 | 职责 | 不应该做 |
|---|---|---|
| main.js | createApp、挂载插件 | 写业务逻辑 |
| App.vue | 应用生命周期、全局样式 | 写 template、写页面逻辑 |
| pages/index/index.vue | 页面 | 写应用级生命周期 |
常见误区
- 误区:App.vue 里写 template 就是首页;正解:App.vue 不渲染模板,首页由 pages.json 的第一项决定。
- 误区:onLaunch 里做所有初始化;正解:onLaunch 时机在各端不同,关键初始化要在首页面 onLoad 兜底。
追问
- Q:全局样式写哪?A:App.vue 的
<style>里,不要写 scoped。 - Q:Pinia 在哪里挂载?A:main.js 里
app.use(createPinia())。
07.2.4.2-005 pages.json 如何注册页面与启动页?
一句话结论
pages.json 的 pages 数组是页面注册的唯一来源,数组第一项是启动页(首页);每个页面项配置 path(路径,不含 .vue)、style(导航栏标题、背景色等)。
概念解释
pages.json 是 uni-app 的"路由配置中心",所有页面必须在这里注册。pages 数组顺序即页面在开发者工具中的顺序,第一项是应用启动后默认打开的页面。每个页面项至少有 path(对应 pages/ 下的目录路径,如 pages/index/index)和 style(窗口样式)。
页面级配置覆盖全局 globalStyle:导航栏标题 navigationBarTitleText、导航栏背景色 navigationBarBackgroundColor、是否显示导航栏 navigationStyle: custom(自定义导航)、下拉刷新 enablePullDownRefresh 等。
页面路径写法有两个常见坑:一是 path 不带 .vue 后缀,写 pages/index/index 而不是 pages/index/index.vue;二是 path 不需要前导斜杠,写 pages/index/index 而不是 /pages/index/index。文件实际位置与 path 必须一一对应,否则编译后路由找不到。
原理流程
pages.json:
{
"pages": [
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } },
{ "path": "pages/detail/detail", "style": { "navigationBarTitleText": "详情" } }
]
}
代码或图示
| 字段 | 含义 | 示例 |
|---|---|---|
| path | 页面路径(相对 pages/) | pages/index/index |
| style.navigationBarTitleText | 导航栏标题 | 首页 |
| style.navigationStyle | custom 为自定义导航 | custom |
| style.enablePullDownRefresh | 是否开启下拉刷新 | true |
| 数组第一项 | 启动页 | pages/index/index |
常见误区
- 误区:pages.json 第一项只是列表顺序;正解:第一项是启动页,改顺序会改首页。
- 误区:新增 .vue 文件自动生效;正解:必须在 pages.json 注册,否则路由找不到。
追问
- Q:如何在 HBuilderX 里快速新增页面?A:在 pages/ 上右键新建页面,IDE 自动写 pages.json。
- Q:启动页参数怎么传?A:启动页不支持外部参数,业务参数通过 onLaunch 或启动逻辑处理。
07.2.4.2-006 pages.json 的 tabBar 怎么配置?
一句话结论
tabBar 字段配置底部 tab 栏:list 数组每项含 pagePath(必须是 pages.json 已注册页面)、text、iconPath/selectedIconPath;tab 页面切换不走 navigateTo,而是用 uni.switchTab。
概念解释
tabBar 是原生底部 tab 栏,配置在 pages.json 顶层。list 项的 pagePath 必须是 pages 数组里注册的页面,且 tab 页面不能通过普通 navigateTo 跳转,必须用 uni.switchTab。图标路径用 static/ 下的图片(绝对路径),不支持网络图片。
color/selectedColor 控制文字颜色,backgroundColor 控制背景,borderStyle 控制上边框。注意 tab 页面的生命周期与普通页面不同:tab 页首次加载后切到其他 tab 再切回,触发的是 onShow 而不是 onLoad。
原理流程
pages.json:
{
"tabBar": {
"color": "#999",
"selectedColor": "#007aff",
"list": [
{ "pagePath": "pages/index/index", "text": "首页", "iconPath": "/static/tab/home.png", "selectedIconPath": "/static/tab/home-active.png" },
{ "pagePath": "pages/user/user", "text": "我的" }
]
}
}
代码或图示
| 字段 | 含义 | 注意 |
|---|---|---|
| color | 未选中文字色 | 16 进制 |
| selectedColor | 选中文字色 | 16 进制 |
| list | tab 项数组 | 2-5 项 |
| pagePath | 页面路径 | 必须已注册 |
| iconPath | 未选中图标 | static/ 本地图 |
| selectedIconPath | 选中图标 | static/ 本地图 |
常见误区
- 误区:tab 页可以用 navigateTo 跳;正解:必须用 switchTab,navigateTo 会失败。
- 误区:tab 图标用网络图;正解:必须是本地 static/ 图片。
追问
- Q:tabBar 能动态改角标吗?A:用
uni.setTabBarBadgeAPI,具体以官方文档为准。 - Q:tab 页 onLoad 何时触发?A:首次切到该 tab 时触发,后续切换只触发 onShow。
07.2.4.2-007 pages.json 的 globalStyle 与页面级 style 如何叠加?
一句话结论
globalStyle 是所有页面的默认窗口样式,页面级 style 覆盖 globalStyle 同名属性;优先级:页面 style > globalStyle > 平台默认。
概念解释
globalStyle 控制全局导航栏标题、背景色、文字颜色、下拉刷新默认开关等。页面 style 只覆盖该页面需要差异化的属性。例如 globalStyle 默认导航栏背景白色,某页面要红色,就在该页面 style 里写 navigationBarBackgroundColor: "#ff0000"。
不要在每个页面 style 里重复写全局一致的配置,那是 globalStyle 的事;只在页面有差异时写页面 style。
原理流程
globalStyle(全局默认)
↓ 页面 style 覆盖
该页面最终窗口样式
代码或图示
| 场景 | 配置位置 |
|---|---|
| 所有页面导航栏白色 | globalStyle |
| 某页面导航栏红色 | 该页面 style |
| 所有页面允许下拉刷新 | globalStyle.enablePullDownRefresh |
| 仅某页面允许下拉刷新 | 该页面 style.enablePullDownRefresh |
常见误区
- 误区:每个页面都写一遍 navigationBarTitleText;正解:全局一致的写 globalStyle,页面只写差异。
- 误区:globalStyle 能控制组件样式;正解:globalStyle 只控制窗口(导航栏、tabBar、背景),组件样式写 CSS。
追问
- Q:如何做沉浸式导航?A:
navigationStyle: custom让页面自定义导航,再用uni.getSystemInfoSync()拿状态栏高度,具体以官方文档为准。 - Q:globalStyle 里能写 tabBar 吗?A:tabBar 是顶层字段,不在 globalStyle 里。
07.2.4.2-008 pages.json 的分包怎么配置?
一句话结论
subPackages(或 subpackages,字段名以官方为准)配置分包,把非首屏页面拆到独立包,进入分包页面时才下载;主包只放启动页与公共资源,用于控制小程序包体大小。
概念解释
小程序平台对主包大小有限制(具体限制以各平台为准,如微信主包 2M、总包 20M,待确认),业务页面多了必须分包。分包配置在 pages.json 顶层 subPackages,每项有 root(分包根目录)与 pages(分包内页面列表)。
主包 = pages 数组里的页面 + common 组件 + static 公共资源。分包页面在 subPackages 里注册,路径是 root + page。分包预下载用 preloadRule 配置:进入某页面时预下载哪些分包,减少用户等待。
分包还有"独立分包"概念(字段名以官方为准):独立分包不依赖主包就能运行,适合营销活动、临时页面,从分享链接直接进入独立分包页,不下载主包。分包间不能互相 import 资源,公共资源必须放主包或单独抽成分包。
原理流程
主包:pages/index/index, pages/user/index + 公共组件 + static
分包A:subPackages[0].root = "pages/order",pages = ["list/list", "detail/detail"]
分包B:subPackages[1].root = "pages/mall",...
preloadRule:进入首页时预下载分包A
代码或图示
| 字段 | 含义 | 注意 |
|---|---|---|
| subPackages.root | 分包根目录 | 与 pages/ 平级或嵌套 |
| subPackages.pages | 分包内页面 | 相对 root |
| preloadRule | 预下载规则 | 按页面配置 |
| 主包 | pages 数组 + 公共 | 必须最小 |
常见误区
- 误区:所有页面放主包;正解:非首屏页面放分包,控制主包大小。
- 误区:分包页面能被主包页面 import;正解:分包内资源只在分包内使用,公共资源放主包或单独分包。
追问
- Q:分包加载时机?A:进入分包页面时才下载,具体规则以平台为准。
- Q:主包引用分包资源会怎样?A:构建报错或资源重复打包,应把公共资源上移到主包。
07.2.4.2-009 pages.json 里如何写条件编译?
一句话结论
pages.json 是 JSON,不支持 // 注释;条件编译用特殊注释写法 /* #ifdef MP-WEIXIN */ 包裹 JSON 片段,构建时按端裁剪。
概念解释
JSON 本身不支持注释,uni-app 提供了一种特殊的注释语法:在 pages.json 里写 /* #ifdef MP-WEIXIN */ ... /* #endif */,编译器识别后保留或裁剪。这种写法可以让 tabBar 配置、globalStyle、页面配置在不同端有差异。
典型场景:微信小程序需要特定的 tabBar 配置,H5 端不需要某页面;用条件编译把差异配置包起来,构建时自动裁剪。
原理流程
{
"globalStyle": {
"navigationBarTitleText": "App"
/* #ifdef MP-WEIXIN */
, "navigationBarBackgroundColor": "#07c160"
/* #endif */
}
}
代码或图示
| 位置 | 条件编译写法 |
|---|---|
| template | <!-- #ifdef MP-WEIXIN --> |
| script | // #ifdef MP-WEIXIN |
| style | /* #ifdef MP-WEIXIN */ |
| json | /* #ifdef MP-WEIXIN */ |
常见误区
- 误区:pages.json 里写
// #ifdef注释;正解:JSON 不支持行注释,用/* #ifdef ... */块注释。 - 误区:条件编译在 JSON 里随意写;正解:逗号位置要正确,否则 JSON 解析失败。
追问
- Q:pages.json 条件编译失败有什么表现?A:构建报错或配置不生效,检查逗号与注释位置。
- Q:manifest.json 也支持条件编译吗?A:支持,同样用
/* #ifdef */语法。
07.2.4.2-010 manifest.json 的基础信息与 appid 怎么填?
一句话结论
manifest.json 的 name 是应用名、appid 是 DCloud 分配的应用标识(uni-app 项目 id,与各小程序平台 appid 不同)、versionName 是版本号、versionCode 是版本码;appid 由 HBuilderX 创建项目时自动生成。
概念解释
manifest.json 是应用元信息配置。name 显示在应用市场与关于页;appid 是 DCloud 平台的项目标识,用于云打包、uniCloud 关联,与微信小程序的 appid 是两回事;versionName 是用户可见版本(如 1.0.0),versionCode 是数字版本码(如 100),App 发版时 versionCode 必须递增。
各端 appid 分别配置:小程序 appid 在 mp-weixin.appid、mp-alipay.appid 等节;H5 不需要 appid;App 端不需要填 appid(用 DCloud appid 关联)。
原理流程
manifest.json:
{
"name": "我的应用",
"appid": "__UNI__XXXXXX", // DCloud 分配
"versionName": "1.0.0",
"versionCode": "100",
"mp-weixin": { "appid": "wx..." }, // 微信小程序 appid
"h5": { ... }
}
代码或图示
| 字段 | 含义 | 示例 |
|---|---|---|
| name | 应用名 | 我的应用 |
| appid | DCloud 项目 id | __UNI__XXXXXX |
| versionName | 用户版本 | 1.0.0 |
| versionCode | 数字版本码 | 100 |
| mp-weixin.appid | 微信小程序 appid | wxabc... |
常见误区
- 误区:DCloud appid 就是微信小程序 appid;正解:两者完全不同,DCloud appid 用于云打包,微信 appid 用于小程序发布。
- 误区:versionCode 不递增也能发版;正解:App 市场要求 versionCode 递增,否则上架失败。
追问
- Q:如何获取 DCloud appid?A:HBuilderX 创建项目时自动分配,CLI 项目在 manifest.json 里点"重新获取"或登录 DCloud 账号。
- Q:换电脑开发 appid 会变吗?A:不会,appid 写在 manifest.json 里,跟着工程走。
07.2.4.2-011 manifest.json 的 App 端配置(权限、模块、分发)怎么写?
一句话结论
App 端配置在 app-plus 节:distribute 配置签名证书与渠道,modules 配置需要的原生模块(推送、地图、支付等),permissions 配置 Android/iOS 权限声明;未勾选的模块不打包进 App,减小包体。
概念解释
app-plus.distribute.android 配置 Android 签名证书(keystore 别名、密码)、minSdkVersion、渠道;app-plus.distribute.ios 配置 iOS 证书与 profile。app-plus.modules 是模块清单:需要哪些原生能力(Push、Maps、Payment、OAuth、Share)就勾选哪些,未勾选不打包,避免包体膨胀。
app-plus.permissions 配置 Android 权限(如 CAMERA、LOCATION)与 iOS 权限说明文案(Info.plist 的 NSxxxUsageDescription)。注意:权限声明与模块勾选是两件事,模块决定打包什么,权限声明决定运行时申请什么。
渠道打包是企业发布的常见需求:在 distribute.android.channels 配置多个渠道(如华为、小米、应用宝),云打包一次生成多个渠道包,用于统计各渠道下载量与崩溃率。渠道号在运行时通过 uni.getSystemInfoSync() 或自定义渠道 API 获取,具体 API 以官方文档为准。
原理流程
manifest.json:
{
"app-plus": {
"modules": { "Push": {}, "Maps": {} },
"distribute": {
"android": { "permissions": ["<uses-permission android:name=\"android.permission.CAMERA\"/>"] },
"ios": { "idfa": false }
},
"permissions": {
"IOSPrivacy": { "NSCameraUsageDescription": "需要相机" }
}
}
}
代码或图示
| 配置节 | 职责 | 注意 |
|---|---|---|
| app-plus.modules | 原生模块勾选 | 未勾选不打包 |
| app-plus.distribute.android | 签名、minSdk、渠道 | 证书密码妥善保管 |
| app-plus.distribute.ios | 证书、profile | 需要 Apple 开发者账号 |
| app-plus.permissions | 权限声明与文案 | iOS 文案必须填写 |
常见误区
- 误区:所有模块都勾选;正解:按需勾选,减小包体与合规风险。
- 误区:iOS 权限文案不填也能上架;正解:缺少 NSxxxUsageDescription 会被 Apple 拒绝。
追问
- Q:App 端推送模块怎么配?A:勾选 Push 模块,配置各推送渠道(个推、华为、小米等),具体以官方文档为准。
- Q:调试版与发布版证书不同怎么办?A:在 distribute 里配置或云打包时选择证书,分环境构建。
07.2.4.2-012 manifest.json 的 H5 路由模式(history/hash)怎么选?
一句话结论
H5 端在 h5.router.mode 配置路由模式:hash 模式默认带 #,部署简单无需服务器配置;history 模式是干净 URL,需要服务器配置 rewrite 到 index.html,否则刷新 404。
概念解释
hash 模式用 URL hash(/#/pages/index/index)做路由,浏览器不向服务器发请求,任何静态服务器都能跑。history 模式用 History API(/pages/index/index),URL 干净,但刷新时服务器会找对应路径的文件,找不到就 404,需要 Nginx/Apache 配置 rewrite 到 index.html。
h5.base 配置部署子路径(如 /app/),部署到子目录时必须配。h5.publicPath 配置静态资源 CDN 路径。
原理流程
hash:https://xxx.com/#/pages/index/index → 服务器无需配置
history:https://xxx.com/pages/index/index → Nginx 需要 try_files $uri /index.html
代码或图示
| 模式 | URL | 服务器配置 | 适用 |
|---|---|---|---|
| hash(默认) | 带 # | 无需 | 快速部署、子路径 |
| history | 干净 URL | 需 rewrite | 正式生产、SEO |
常见误区
- 误区:history 模式直接部署就好;正解:必须配服务器 rewrite,否则刷新 404。
- 误区:h5.base 不用配;正解:部署到子目录时必须配 base,否则资源 404。
追问
- Q:微信内嵌浏览器支持 history 吗?A:支持,但要保证服务器 rewrite 正确。
- Q:history 模式下微信分享路径问题?A:分享链接是 history 路径,需要服务器正确处理。
07.2.4.2-013 easycom 自动引入规则是什么?
一句话结论
easycom 是 uni-app 的组件自动引入机制:在模板里使用组件时,按约定路径自动 import,不需要手动写 import 与 components: {};约定是 components/组件名/组件名.vue 或 uni_modules/插件名/components/组件名/组件名.vue。
概念解释
默认 easycom 规则扫描两个位置:components/组件名/组件名.vue 与 uni_modules/*/components/组件名/组件名.vue。在模板里写 <uni-badge />,编译器自动找到对应文件并引入,无需手动 import。
收益是减少样板代码,代价是"隐式依赖":看模板不知道组件从哪来,路径不对就静默失败。easycom 在 pages.json 的 easycom 字段可自定义规则(如匹配 ^u-(.*) 指向 uview-ui)。
原理流程
模板写 <my-card />
↓ easycom 扫描
查找 components/my-card/my-card.vue
↓ 自动 import
编译产物
代码或图示
| 位置 | 命名规则 |
|---|---|
| components/ | components/组件名/组件名.vue |
| uni_modules/ | uni_modules/插件/components/组件名/组件名.vue |
常见误区
- 误区:easycom 会扫描所有 .vue;正解:只按约定路径扫描,文件名必须与组件名一致。
- 误区:easycom 找不到组件会报错;正解:通常静默失败(组件不渲染),需检查路径与命名。
追问
- Q:如何自定义 easycom 规则?A:在 pages.json 的 easycom.custom 里写正则与替换路径,具体语法以官方文档为准。
- Q:easycom 影响性能吗?A:构建期扫描,运行时无开销,但组件按需引入,不影响包体。
07.2.4.2-014 uni_modules 与 npm 依赖怎么取舍?
一句话结论
uni_modules 放"端能力插件"(含 uts/nvue/原生代码、多端组件),npm 放"纯 JS/TS 逻辑库"(如 dayjs、lodash、axios);两者混用不冲突,但不要把端能力插件当 npm 包装。
概念解释
uni_modules 的插件自带多端源码(uts、nvue、js),编译器按目标端裁剪;npm 包是纯 JS,不感知端差异。如果一个库是纯逻辑(格式化、加密、工具函数),走 npm;如果一个库是组件、原生能力、多端 UI,走 uni_modules。
判断依据:插件目录里是否有 utssdk/、app-native/、components/ 等端特定目录,有就是 uni_modules;只有 index.js 与 package.json 就是 npm 包。
还有一个边界是"业务内部组件":多个项目复用的业务组件库,推荐做成内部 uni_modules 发到内部 npm 源或 git 仓库,团队统一安装;只在一个项目内用的公共组件,放 components/ 目录即可,不要都塞 uni_modules。npm 包在小程序端有一个常见坑:依赖浏览器 API(如 window、document)或 Node API(如 fs、path)的包不能直接用,必须选小程序兼容版本或找替代库;uni-app 的运行时已经把部分浏览器 API 做了适配(如 uni.request 替代 fetch),但不是全部。
原理流程
需求 → 是纯逻辑库吗?
├─ 是 → npm install
└─ 否(组件/原生/多端)→ 插件市场下载到 uni_modules/
代码或图示
| 类型 | 来源 | 示例 |
|---|---|---|
| 纯逻辑库 | npm | dayjs、axios |
| 多端组件 | uni_modules | uni-ui、自定义业务组件 |
| 原生能力 | uni_modules | uts 插件、nvue 模块 |
| 内部通用组件 | uni_modules 或 components/ | 业务卡片 |
常见误区
- 误区:所有依赖都走 npm;正解:端能力插件必须走 uni_modules,否则多端源码不被识别。
- 误区:uni_modules 插件要手动 import;正解:组件可通过 easycom 自动引入,工具类手动 import。
追问
- Q:npm 包在小程序端能用吗?A:纯 JS 包能用,依赖浏览器 API 或 Node API 的包不能直接用。
- Q:uni_modules 里的 npm 包能被项目引用吗?A:能,插件自己的 node_modules 与项目隔离。
07.2.4.2-015 环境变量与多环境构建怎么配?
一句话结论
uni-app 通过环境变量区分开发/生产环境:构建时用命令行参数(--mode)或 process.env.NODE_ENV,业务代码用 import.meta.env(Vite 链)或 process.env(Vue2 链)读取;多环境配置在 .env 文件里写。
概念解释
Vite 链用 .env、.env.development、.env.production 文件,变量以 VITE_ 前缀暴露给业务代码,用 import.meta.env.VITE_XXX 读取。构建命令 vite build --mode staging 加载 .env.staging。
App 端与小程序端的环境变量在构建时注入,运行时无法动态切换;多环境打包靠不同命令行构建不同产物。注意:小程序的请求域名是在后台配置的,环境变量只能改 baseURL,域名白名单仍需在各端后台配置。
原理流程
.env.development:VITE_API_BASE=https://dev.xxx.com
.env.production:VITE_API_BASE=https://api.xxx.com
业务:const base = import.meta.env.VITE_API_BASE
构建:npm run build:h5 -- --mode production
代码或图示
| 方式 | Vite 链 | Vue2 webpack 链 |
|---|---|---|
| 读取变量 | import.meta.env.XXX | process.env.XXX |
| 环境文件 | .env.* | .env.* |
| 变量前缀 | VITE_ | 自定义 |
| 多环境命令 | --mode staging | --mode staging |
常见误区
- 误区:环境变量能在运行时切换;正解:构建时注入,运行时固定,切换环境要重新构建。
- 误区:小程序请求域名跟着环境变量变;正解:域名白名单在小程序后台配置,环境变量只改 baseURL。
追问
- Q:如何在 manifest.json 里读环境变量?A:manifest.json 是静态 JSON,不支持运行时变量;多环境 manifest 用条件编译或构建脚本生成。
- Q:敏感信息(密钥)能放环境变量吗?A:前端环境变量会打进产物,敏感信息放服务端,不要放前端。
07.2.4.2-016 TypeScript 在 uni-app 里怎么用?
一句话结论
Vue3 + Vite 链原生支持 TypeScript:<script setup lang="ts"> 直接写,类型定义在项目里建 types/ 目录;uni-app 提供了 @dcloudio/types 类型包(具体包名以官方为准),覆盖 uni.xxx API。
概念解释
Vite 链用 TS 零配置:.vue 文件里写 <script setup lang="ts">,Vite 自动处理。类型定义:uni-app 官方提供 @dcloudio/types(待确认包名与版本),在 tsconfig.json 的 types 里引用,覆盖 uni.request、uni.navigateTo 等全局 API。
业务类型(接口返回、store 状态)在项目 types/ 目录定义,用 interface 或 type。注意:uni-app 的部分内置组件 props 类型是宽松的,复杂组件可能需要自己补类型声明。
Pinia 的 store 类型化是 Vue3 链的标准做法:defineStore 用 state 与 actions 组合式写法,自动推导 state 类型;调用方 useStore() 拿到带类型的 store。请求封装(uni.request Promise 化)也建议加泛型,让接口返回值自动推导。
原理流程
<script setup lang="ts">
interface User { id: number; name: string }
const user = ref<User>({ id: 1, name: 'a' })
uni.request({ url: '/api' }) // 类型来自 @dcloudio/types
</script>
代码或图示
| 场景 | 做法 |
|---|---|
| 页面 TS | <script setup lang="ts"> |
| uni API 类型 | @dcloudio/types |
| 业务类型 | types/ 目录 |
| 组件 props 类型 | defineProps<{...}>() |
常见误区
- 误区:uni-app 不支持 TS;正解:Vue3 链原生支持,Vue2 链需 vue-property-decorator 方案。
- 误区:所有 uni API 都有完整类型;正解:部分 API 类型是宽松的,需自己补声明。
追问
- Q:Vue2 链能用 TS 吗?A:能,用 class 组件与 vue-property-decorator,但体验不如 Vue3。
- Q:TS 编译报错怎么办?A:检查 tsconfig.json 的 types 是否包含 @dcloudio/types,以及 include 范围。
07.2.4.2-017 综合题:新项目选 HBuilderX 工程还是 CLI 工程?
一句话结论
团队协作、CI、多人开发、需要版本管理标准流程,选 CLI;个人快速原型、学习、需要云打包与真机运行一键集成,选 HBuilderX。源码结构一致,选错可迁移。
概念解释
判断树:第一步看团队是否多人协作(是 → CLI);第二步看是否有 CI/CD(是 → CLI);第三步看成员是否熟悉 npm 流程(是 → CLI);第四步看是否需要快速云打包(是 → HBuilderX)。
CLI 的劣势是初次配置证书、云打包、真机运行链路要自己搭;HBuilderX 的劣势是工程依赖 IDE,CI 不友好。源码结构一致意味着选错可迁移,但迁移成本在团队流程与 CI 配置,不是代码本身。
原理流程
多人协作 + CI + 标准 npm 流程 → CLI
个人 + 快速原型 + 云打包 → HBuilderX
代码或图示
| 决策因素 | CLI | HBuilderX |
|---|---|---|
| 多人协作 | 优 | 中 |
| CI/CD | 优 | 差 |
| 编辑器自由 | 优 | 差 |
| 云打包一键 | 中 | 优 |
| 学习成本 | 中 | 低 |
常见误区
- 团队全选 HBuilderX 因为"新建项目快";正解:长期看 CI 与协作成本更高。
- 以为 CLI 不能云打包;正解:CLI 也能调云打包命令,只是不如 IDE 一键。
追问
- Q:混合团队怎么选?A:统一选 CLI,IDE 自由,HBuilderX 也能打开 CLI 工程。
- Q:CLI 工程如何真机运行?A:用
npm run dev:app配合 HBuilderX 真机运行或自有调试链路,具体以官方为准。
07.2.4.2-018 综合题:pages.json 配完后页面白屏或路由 404,怎么排查?
一句话结论
按四步排查:页面是否在 pages.json 注册、路径是否与文件位置一致、第一项是否为启动页、条件编译是否裁剪了该端;再看控制台报错与构建产物。
概念解释
常见原因:一是页面 .vue 文件建了但没在 pages.json 注册;二是 pages.json 路径写错(如多了 .vue 后缀、少了目录层级);三是第一项不是预期启动页;四是条件编译把该端页面裁掉了;五是文件编码或语法错误导致构建失败。
排查顺序:先看构建是否报错(控制台),再看 pages.json 注册列表,再核对路径与文件位置,最后看条件编译。
原理流程
白屏/404
↓
1. 构建是否报错? → 是:修语法/配置
2. 页面是否在 pages.json 注册? → 否:注册
3. path 是否与文件位置一致? → 否:修正路径
4. 第一项是否为启动页? → 否:调整顺序
5. 条件编译是否裁掉该端? → 是:补条件或去掉裁剪
代码或图示
| 症状 | 可能原因 |
|---|---|
| 控制台报 "page not found" | 未注册或路径错 |
| 启动白屏 | 第一项错或首屏报错 |
| 某端能跑某端不行 | 条件编译或平台差异 |
| 构建就报错 | 语法或 JSON 逗号错 |
常见误区
- 只改代码不看 pages.json;正解:uni-app 路由是配置驱动,pages.json 是第一检查点。
- 忽略条件编译;正解:某端单独白屏先查条件编译是否把页面裁掉。
追问
- Q:如何看构建后的 pages.json?A:构建产物目录里找各端工程的 pages.json,核对生成结果。
- Q:tab 页 switchTab 失败怎么办?A:检查 pagePath 是否在 tabBar.list 与 pages 都注册了。