罗罗编程学习记录
本页内容 展开查看

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.setTabBarBadge API,具体以官方文档为准。
  • 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 都注册了。