写这篇教程的起因很简单我近几年接手的 uniapp 项目里几乎每个项目初期都会出现同一类问题——页面能跑但底栏样式不对、扫码权限没有、H5 端接口跨域、打包后图标是默认的。这些问题的根子几乎都指向同一个地方全局配置没做好。uniapp 的全局配置说白了就是项目初期那几个“看不见摸不着”的文件在起作用。很多人拿到模板就闷头写页面等回头再改这些配置改动成本已经很高了。这篇内容我会从一个实际开发者的角度把 uniapp 全局配置涉及的文件、参数、顺序和常见坑完整过一遍。无论你是第一次建 uniapp 项目还是已经做好几个项目但总被配置问题绊住脚这篇都能当一份“翻烂了也不亏”的参考手册用。1. 先搞清楚全局配置有哪些文件1.1 五大全局配置文件的职责划分uniapp 项目的全局配置并不集中在某一个文件里而是分散在几个固定位置共同协作。我习惯把它们分成五块pages.json掌管页面路由、原生导航栏、tabBar、easycom 规则。页面要能跳转、底部导航要能显示全靠它。manifest.json掌管应用级信息包括应用名称、AppID、各端模块权限、SDK 参数、打包配置。小程序端 appid、App 端麦克风权限、H5 端的跨域转发都从这里配。uni.scss全局样式变量文件。里面定义的 SCSS 变量会注入到每个页面的样式编译中适合统一主题色、圆角、字体大小。App.vue应用入口组件。写过小程序的人可以把它理解为 app.json app.js 的合体里面有 onLaunch、onShow、onHide 这几个应用级生命周期还有 globalData 可以做简单的全局数据存储。main.jsVue 实例创建入口。全局组件注册、Vue.prototype 上的全局方法、全局样式引入、store 挂载都在这里完成。这五个文件的关系可以类比成开一家店pages.json 是店面布局图决定了顾客走到哪看到什么manifest.json 是营业执照和物业合同决定你能做什么业务uni.scss 是装修风格规范所有房间统一用同一种色调App.vue 是店里的开关总闸开门、打烊、店庆活动都在这里管main.js 是前台把店里的公共设施挨个装好。1.2 配置顺序先全局后页面我见过太多新项目一开始 pages.json 里只留了一个默认 index 页开发到一半才想起来要加 tabBar。结果呢加 tabBar 时要手动把一堆页面路径注册进去还要重新调整导航栏样式工作量翻倍。全局配置的正确打开方式是在写第一个页面之前先把这五个文件全部过一遍。我自己的习惯顺序是先改 manifest.json 的基础信息应用名称、AppID、需要的模块权限。再填 pages.json确定首页、页面路径、tabBar 结构、全局导航栏颜色。接着写 uni.scss把主题色、通用间距、字号变量固定下来。然后设计 App.vue 的全局生命周期逻辑和 main.js 的挂载内容。最后才开始写具体页面。这个顺序看起来简单但能避免后面大量返工。尤其是 uni.scss 里的颜色变量如果你做到一半才改主题色全站页面的颜色也跟着变但这种变化是可控的、值得的反过来如果你没定义变量、把颜色写死在每个页面里那改起来就是灾难了。2. pages.json页面路由与窗口表现的“第一站”2.1 页面注册与启动页顺序pages.json 里的 pages 数组是路由注册表第一个元素决定了应用启动后进哪个页面。这个顺序非常容易踩坑——很多人以为它只是列表其实第一项就是默认启动页。想改启动页直接把目标页面移到数组第一位就行不需要额外配置。另外还有一个细节pages 数组里页面路径会被编译进分包或主包的页面列表中如果路径写错跳转时会直接报 page not found。这类错误很难排查因为它不在编译期暴露而是运行到那一跳才崩。我通常会在 pages.json 里给每个页面加上 style 节点哪怕只是设置 navigationBarTitleText。这样保证每个页面进去时导航栏标题是明确的不会出现标题还是上一页残留的情况。{ pages: [ { path: pages/index/index, style: { navigationBarTitleText: 首页, enablePullDownRefresh: true } }, { path: pages/order/order, style: { navigationBarTitleText: 订单 } } ] }2.2 全局导航栏与 tabBar 配置globalStyle 是页面全局窗口表现配置。它定义的 navigationBarBackgroundColor、navigationBarTextStyle、backgroundColor 会对所有页面生效除非页面自己在 style 里覆盖。这个覆盖优先级一定要记牢页面 style 优先于 globalStyle。所以如果你发现某个页面导航栏颜色不对先看它自己的 style再翻全局配置别一上来就怀疑全局改坏了。tabBar 的配置我单独说因为这里坑最多list 最少 2 项、最多 5 项。pagePath 必须和 pages 数组里的路径完全一致多一个斜杠都不行。iconPath 和 selectedIconPath 只能使用本地图片不支持网络图片。图片建议放在 static 目录下路径用绝对路径写法以 / 开头。图标尺寸官方建议 81x81px实际我会用 40x40pt 对应 2x 和 3x 图文件大小控制在 40KB 以内。真机上图标不显示多半是图片太大或者格式不对。tabBar 的“闪烁”问题也跟配置有关后面第 7 章我再展开。2.3 easycom 自动导入组件规则easycom 是 pages.json 里一个容易被忽视但极其实用的配置。它解决的问题是开发时不想写 import 引入组件。uniapp 默认开启了 easycom会自动扫描 components/uni_modules 目录下的组件只要组件路径符合规则页面里直接用标签名就能渲染。默认规则是^u-(.*)会去/components/u-$1/u-$1.vue查找但自定义规则是完全可以覆盖的。比如我把公共组件统一放在/components/下命名格式是c-xxx.vue那可以这样配{ easycom: { autoscan: true, custom: { ^c-(.*): /components/c-$1.vue } } }这里有个容易踩的坑如果没有配置 custom 规则又在页面里用了不符合默认规则的标签uniapp 不会报编译错误只会在控制台提示找不到组件页面片段直接不渲染。这种问题排查起来费时间最好在项目初期就把 easycom 规则定好。2.4 condition 启动模式调试直达目标页condition 配置对日常开发效率影响很大。它是启动模式配置可以让我们在小程序开发者工具或 H5 调试时直接启动到指定页面而不是每次从首页一步步跳过去。{ condition: { current: 0, list: [ { name: 订单详情调试, path: pages/order/detail, query: id123 } ] } }配置之后在微信开发者工具里选择“自定义编译条件”就能直接进入订单详情页query 参数也会自动带上。这个功能特别适合调试深层级页面不用每次从首页走流程。3. manifest.json应用信息、模块权限与打包参数3.1 应用名称、AppID 与版本号manifest.json 里最基础的配置是应用的名称和 AppID。名称直接决定用户在手机桌面上看到的名字小程序端则显示在微信里。AppID 分几种DCloud appid 是 uni-app 项目的唯一标识创建项目时自动生成微信小程序 appid 需要在 mp-weixin 节点下配置不填的话微信开发者工具里会一直提示无合法 appid支付宝、百度等小程序同理。版本号这块很多人会漏。manifest.json 里的版本名和版本号是打包时写入安装包的如果不上架应用市场可能无所谓但只要上架版本号规则就得提前规划好。我一般用版本名 1.0.0、版本号 100 这种对应关系每次发版递增。3.2 模块权限配置别让小功能变成打包事故模块权限是 App 端特有的配置。在 HBuilderX 的 manifest 可视化界面里“App 模块配置”一栏列了几十个可选模块包括相机、定位、地图、蓝牙、NFC、支付、分享、推送等。为什么强调这个因为 App 端打包时只有勾选了对应模块相关原生能力才会被打进安装包。常见的事故场景是代码里写了uni.scanCode({})扫码功能真机调试没问题但打包成 apk 后扫码直接无效打开摄像头黑屏——大概率就是 manifest 里没有勾选“扫码”模块。我印象很深的一次是在小米手机上测试一个 App录音功能在开发版本里一切正常打包后麦克风权限怎么都弹不出来。折腾了半天才发现 manifest 里没勾选“麦克风”模块权限系统层面直接没声明这个权限代码里自然拿不到。所以涉及原生能力的代码一定要养成交叉检查的习惯开发环境跑业务逻辑打包前过一遍模块配置。常用模块就那几个但漏一个就是事故。3.3 图标、启动图与各端打包参数图标和启动图的配置决定了这个 App 安装到手机上看起来“像不像个正经产品”。HBuilderX 的 manifest 可视化界面里有自动生成图标的功能上传一张 1024x1024 的源图会自动切成各尺寸。这个功能省事但要注意源图四周留白否则切出来的圆角图标边缘会很挤。启动图splash在 App 端的表现比较特殊尤其 Android 厂商定制系统对启动图尺寸要求不统一。适配成本很高我的做法是用 HBuilderX 的自动生成启动图功能至少保证大多数机型不出现黑屏或拉伸。微信小程序端的打包参数也在这里配置包括小程序的 appid、项目名称等。如果你要用 uniapp 打包微信小程序发行前确保 mp-weixin 节点下的 appid 已经填好否则生成的代码在微信开发者工具里没法正常运行。4. 全局样式、生命周期与公共逻辑的统一入口4.1 uni.scss主题变量在全局生效的原理uni.scss 这个东西很多人以为它只是个普通样式文件其实它的特殊之处在于里面的变量会被自动注入到每个页面的 scss 编译上下文中。也就是说你在 uni.scss 里定义$brand-color: #2979ff;随便哪个页面的style langscss里都能直接用不需要手动 import。这意味着它是做主题变量统一管理的天然位置。我一般会在 uni.scss 里集中定义品牌主色、辅助色、功能色成功/警告/失败字体大小梯度通用间距8px、16px、24px圆角大小阴影层级有一个限制必须知道uni.scss 里不能写普通的 class 样式只能写 SCSS 变量、mixin、function。如果你往里面塞了 class会被注入到每个页面造成样式重复和权重混乱。主题切换的实现也依赖这里。如果你想做深色模式可以在 uni.scss 里定义好颜色变量然后在 App.vue 或 main.js 里根据当前模式给根节点换 class页面样式里用变量值响应变化。4.2 App.vue应用生命周期与全局数据App.vue 的结构和普通页面组件不一样它没有 template只有 script 和可选 style。官方生命周期包括 onLaunch应用初始化、onShow应用从后台进入前台、onHide应用退到后台。我在 onLaunch 里一般做三件事初始化登录态从本地存储读取 token校验是否过期。版本更新检查在小程序端可以调用更新 API 做静默更新。全局数据预加载比如用户基本信息、配置项等拉到后存到 store。注意App.vue 的 onLaunch 在小程序端每次冷启动都会执行而 H5 端刷新页面也会执行App 端则根据平台有所不同。如果你的逻辑涉及多端不能假设 onLaunch 只执行一次。globalData 是 App.vue 里可以直接挂的全局数据对象可以通过getApp().globalData访问。但它不是响应式的页面里不能依赖它做数据绑定。适合放静态配置、登录 token、设备信息这类“读一次就行”的数据。真正需要响应式的全局状态老老实实用 vuex 或 pinia。4.3 main.js全局挂载与 Vue 2/3 写法差异main.js 是 Vue 实例创建的地方也是全局能力统一挂载的入口。随着 uniapp 从 Vue 2 迁移到 Vue 3现在新创建的项目默认都是 Vue 3这里的写法差异很大。Vue 2 时代挂载全局方法的经典写法是import Vue from vue Vue.prototype.$utils utilsVue 3 里不再有 Vue.prototype改成import { createSSRApp } from vue export function createApp() { const app createSSRApp({ // 根组件配置 }) app.config.globalProperties.$utils utils return { app } }我见过不少从 Vue 2 转到 Vue 3 的项目改完组件之后忘了改 main.js 这层导致this.$utils报 undefined。全局方法挂载之后在单文件组件里通过this.xxx访问这一点两个版本是一致的。main.js 里还适合做这些事引入全局样式文件如 App.scss注册全局组件通过 app.component挂载 pinia / vuex引入并注册 uv-ui、uni-ui 等组件库5. 网络请求全局封装与跨域转发5.1 请求模块为什么要全局封装uniapp 自带的 uni.request 能满足基本需求但真实业务里几乎没法直接用。原因很简单每个接口都要拼 baseURL、都要带 token、都要处理登录过期、都要统一报错。这些事情如果散落在每个页面里后续维护就是噩梦。我建议所有项目一开始就做一个全局请求模块放在 utils/request.js 里。核心逻辑包含拼接接口地址和 baseURL从全局配置或 storage 里读取 token注入请求头统一处理 HTTP 状态码和业务状态码401 时清除登录态跳转登录页网络异常时统一给用户 Toast 提示这个封装不复杂但能统一吃掉一半的异常分支后续改接口地址、改鉴权方式都只动一个文件。5.2 多环境切换的全局配置方案开发环境、测试环境、生产环境的接口地址通常不一样。我见过有人每次发版前手动改 baseURL这是项目事故的高发源头。推荐的做法是建一个 config.js根据运行环境自动选择接口地址const ENV { development: { baseURL: https://dev-api.example.com }, production: { baseURL: https://api.example.com } } const currentEnv process.env.NODE_ENV production ? production : development export default { ...ENV[currentEnv] }process.env.NODE_ENV 在 uniapp 里会由编译工具自动注入开发者工具和 H5 开发时是 development发行时是 production。用这个方式整套环境的切换就是自动的不需要开发者每次手动干预。5.3 H5 开发时的跨域转发配置浏览器本地调试 H5 页面时最常见的问题是跨域页面跑在 localhost:8080接口地址是 https://api.example.com浏览器直接拦截请求。这时就需要开发服务器把 /api 开头的请求转发到真实接口地址让浏览器认为自己请求的是同源地址。这个配置在 manifest.json 的 h5 节点下通过 devServer 设置。实际操作里我会在 h5.devServer 里配置上下文匹配规则把/api前缀的请求全部转发到目标服务器并开启跨域相关的头部修改项。配完之后本地代码里请求路径写/api/user/info开发服务器会把它转发到https://api.example.com/api/user/info浏览器控制台 Network 面板里看到的还是相对路径但响应内容是真实的。关于 Network 面板显示 unavailable 的问题大概率跟这个配置有关devServer 没有正确转发或者目标服务器证书不受信任请求本身没发出去。后面第 7 章再细说排查思路。6. 打包与上架前的全局配置检查清单6.1 微信小程序端打包前要确认什么用 uniapp 打包微信小程序流程上很简单manifest 里填好小程序 appid点发行选小程序-微信编译后产出一个 dist 目录然后在微信开发者工具里导入这个目录。但有很多细节会让这个流程不顺利。我列一个自己的检查清单mp-weixin 节点下的 appid 是否填对是不是测试号。小程序基础库版本是否满足项目中使用的 API 要求。比如你用了较新的 API但基础库设置过低真机上就会白屏或接口报错。基础库版本在微信开发者工具的“详情-本地设置”里改也可以在 manifest 的 mp-weixin 节点下指定。是否开启了微信小程序的组件按需注入。这个能明显减小包体建议开启。分包配置是否合理。如果主包超过 2MB 上限编译时会直接失败。6.2 Android 打包、签名与市场审核Android 打包分云打包和离线打包。云打包是在 HBuilderX 里直接生成 apk/aab适合大多数开发者离线打包需要下载 Android 工程在 Android Studio 里手动集成适合需要深度定制原生功能、接入特殊 SDK 的场景。云打包之前必须做的是生成 Android 签名证书。签名证书是 App 的唯一身份标识后面每次升级都必须用同一份证书签名否则系统会认为是两个不同的 App。这个证书一旦丢失几乎等于 App 无法更新。如果你要用离线打包并且在 Android 工程里引入 uts 插件需要在原生工程里配置插件依赖。简单说uts 插件是 uni-app 的一种扩展方式可以用类 TS 语法写原生逻辑再被打包成原生插件。离线打包时这些插件会被编译进原生工程中不再依赖 HBuilderX 运行时。上架安卓应用市场之前还有一个绕不开的环节隐私合规。现在主流市场对 App 获取权限的说明要求很严格应用启动时不能强制索要无关权限隐私政策里必须列清楚每一项权限用途且所有权限都要在 manifest 里声明。6.3 iOS 打包证书与提审注意点iOS 打包比 Android 要复杂一些因为需要签名机制和审核流程。首先需要 Apple Developer 账号然后创建证书、Bundle Identifier再生成描述文件。HBuilderX 云打包时只需要上传 p12 证书和描述文件其他由云端处理。提审 App Store 时要特别注意权限用途说明必须写清楚。iOS 对隐私非常严格麦克风、摄像头、定位的用途说明如果与功能不符会被直接打回。如果 App 有用户生成内容UGC需要提供举报和屏蔽功能否则审核会卡住。广告标识符IDFA相关的问题也很敏感如果 App 用到了广告 SDK需要额外配置。用 uniapp 开发 iOS 上架除了这些通用规则还要注意原生化程度。纯 uniapp 项目只要按照标准配置打包审核通过率本身是不错的但如果用了大量自定义原生插件就需要多留出测试时间。7. 高频问题排查实录全局配置引发的连环坑7.1 底部导航闪烁、扫码不清晰与权限缺失底部 tabBar 闪烁。这个问题在小程序端和 App 端都出现过。常见原因有两个一个是 tabBar 图标文件过大导致切换页面时图标加载慢视觉上像闪烁另一个是页面 onShow 里频繁调用uni.setTabBarItem动态改文字或图标每次切页都重绘一次。我的建议是tabBar 图标控制在 40KB 以内不要动态改 tabBar 文案除非业务必须。必须动态改时也要加判断只在值变化时才调用 setTabBarItem。扫码不清晰。真机上uni.scanCode打开摄像头后成像模糊多数不是代码问题而是权限和硬件配合问题。先确认 manifest 里勾选了相机和扫码模块再检查摄像头镜头是否有遮挡。如果是自定义扫码页面注意把预览区域设置大一些扫描框太小会导致自动对焦困难。小米手机麦克风权限缺失。第 3 章提过这个问题排查思路排序是先看 manifest 是否勾选麦克风模块再看代码里有没有主动申请权限uni.authorize最后看隐私政策里有没有声明麦克风用途。很多厂商 ROM 对权限授予有额外要求隐私声明里没写用途系统也会直接拒绝授权弹窗。7.2 视频自动播放、弹出层滚动与 webview 返回视频自动播放。小程序端对 video 自动播放限制很严格部分平台必须用户手动点击后才能播放。如果你的业务必须在进入页面后自动播放可以尝试设置autoplay加muted静音播放有些平台允许静音自动播放用户点击后再开声音。另一个方案是预播放提前创建 video context 并加载资源但不播放等用户进入交互时立即播放。弹出层打开后底部滚动。底部页面跟着弹出层一起滚动是很影响体验的问题。解决思路是弹出层打开时锁住页面滚动。可以给页面的根节点动态加overflow: hidden更推荐的做法是使用支持 lock-scroll 的弹层组件比如 uv-ui 的 popup 组件自带这个能力。webview 的返回方式跟常规页面不一致。webview 内嵌的是一个独立网页用户在里面有独立的浏览历史。常规页面返回会触发页面的 onBackPress但 webview 内的返回是网页自身的历史回退。处理方式是监听 webview 的页面状态当用户点击导航栏返回时如果网页有历史记录先执行uni.webView.navigateBack()回退网页历史没有历史时再关闭 webview 页面回到上一页。7.3 Network unavailable 与多端表现不一致H5 启动后 Network 显示 network: unavailable。这个问题我在 HBuilderX 内置浏览器和微信开发者工具里都遇到过。表象是打开页面后 Network 面板显示请求不可用实际原因是接口请求被跨域拦截或 devServer 转发没生效。排查顺序建议是先看 manifest 的 h5 节点下 devServer 是否正确配置了转发规则。再看请求地址是否以/api开头是否命中了转发规则。最后在浏览器里直接访问接口地址确认后端服务本身是通的。多端表现不一致。同一个页面在小程序端正常、H5 端异常或者反过来这是 uniapp 开发的常态。原因多数不是业务代码而是环境和 API 差异。排查这类问题时先看控制台报错再看条件编译分支。比如小程序端独有的wx.xxxAPI 不能直接在 H5 端调用浏览器端独有的window.xxx也不能在小程序端直接用。这个规则可以通过条件编译来解决但前提是你得把公共逻辑和差异化代码拆开。最后再分享一个我在多个项目里验证过的习惯新建 uniapp 项目后不管业务多急我都会先花半小时把 manifest、pages.json、uni.scss、App.vue、main.js 这五个文件从头到尾过一遍。应用名称、AppID、界面主色、tabBar 结构、请求基类这些决定了项目后面所有代码怎么写。很多所谓的“疑难 bug”追到最后都只是当初全局配置少勾了一个模块、少配了一个字段。配置这件事做在前面后面写代码就能少踩一半的坑。