企业官网建设流程全解析

1. 页面顶部那条"白条"到底是什么

做 uni-app 项目的人，几乎都遇到过这样一个瞬间：页面设计稿是全屏沉浸式的，头部自定义、内容直接顶到状态栏下方，结果真机一跑，顶部硬生生多出一条白底、带标题、甚至带返回箭头的横条，把整个布局往下顶。你去改 CSS，把容器margin-top设成负值，改完发现 H5 端好了，小程序端还是那样，App 端又是另一种表现。这个"白条"就是navigationBar系列配置渲染出来的原生导航栏，它不属于你的页面 DOM 结构，而是宿主环境的原生视图层，所以用常规的position: fixed、z-index、负边距去跟它较劲，大概率是徒劳的。

先把概念理清楚，对后面所有操作都有帮助。uni-app 里所谓"导航栏"，在页面级配置中由pages.json的navigationBar一组字段控制，包括navigationBarTitleText、navigationBarBackgroundColor、navigationBarTextStyle。另外还有全局级配置globalStyle，作用于所有页面。这两层的关系是：页面配置覆盖全局配置。而"原生导航栏不显示"这件事，在 uni-app 的语境里并不存在一个叫navigationBarShow: false的开关，官方提供的是navigationStyle这个字段，取值default或custom。设为custom时，原生导航栏整体隐藏（App 端保留状态栏区域的空间逻辑，小程序端交由开发者自己处理顶部区域），这时你才有完整的页面区域可以自由布局。

很多人第一次踩的坑就在这儿：以为要"隐藏导航栏"，于是去找各种 show/hide 开关，甚至尝试改navigationBarBackgroundColor为transparent来"伪装隐藏"。透明背景确实能让那条横幅看不见，但它占据的高度还在，标题文字和返回按钮也还在，属于典型的治标不治本。真正的做法只有一条路：navigationStyle: custom。判断标准很简单——如果你需要在原导航栏的位置放自己的自定义组件、图片或者搜索框，就必须走custom；如果你只是想去掉标题文字但保留高度，那才轮到透明背景这类取巧方案。这两者的适用场景完全不同，后文会分别讲。

这里还有一个非常容易被忽略的前提：pages.json是编译期配置，修改后必须重新编译才会生效，热更新对它的处理并不可靠。我在实际项目里见过至少三次"改了没生效"的排查，最后发现是开发者工具没有重新跑构建，光保存文件是不够的。所以后面所有配置改动，请默认伴随一次完整重启编译，尤其是 App 端真机调试时，配置缓存尤其顽固。

2. navigationStyle 的生效边界：三端差异必须提前想清楚

navigationStyle: custom写进pages.json只需要一行，但它带来的连锁反应在三端完全不一样。如果不管这些差异就闷头往下做，等到快上线才发现某个端页面被状态栏压住、或者右上角胶囊按钮挡住内容，返工成本很高。所以这一节把三端的实际表现摊开讲。

2.1 小程序端：胶囊按钮区域是你必须自己让开的

小程序端支持navigationStyle: custom，配置后会隐藏原生导航栏，但右上角的胶囊按钮（菜单按钮）不会消失，它属于系统级控件，开发者没有权限隐藏。这意味着页面右上角大约一个胶囊高度加边距的区域是"禁区"，你的自定义头部必须主动避开。通常的思路是在自定义导航栏组件里预留高度，或者直接用uni.getMenuButtonBoundingClientRect()拿到胶囊的位置信息，动态计算顶部安全区。

这个 API 返回的是胶囊的top、bottom、left、right、width、height，在页面onLoad或onReady之后调用比较稳妥。实践中常见的写法是用胶囊的top值作为自定义导航栏内容区的上边距，用height对齐内容高度，这样视觉上自定义栏和胶囊能保持同一水平线。注意不同机型、不同小程序平台（各家小程序对该配置的支持细节有出入）返回的数值会有差异，不要硬编码 44px 或 88rpx 这种数值，一定要动态取。我踩过一次坑：在开发机上写死了一个高度，自测没问题，换到另一台手机上胶囊位置偏下，自定义头部和胶囊直接重叠了两三个像素，视觉上非常难受。

另外要留意，小程序端隐藏原生导航栏后，页面不再有系统返回按钮。如果这个页面是二级页，你必须自己在自定义头部画一个返回按钮，并调用uni.navigateBack()。有同学会想用uni.showNavigationBarLoading之类的 API 补救，那些跟导航栏显隐无关，方向就错了。

2.2 App 端：状态栏高度是另一套逻辑

App 端隐藏原生导航栏后，页面内容会从屏幕最顶部开始绘制，也就是会覆盖到状态栏（显示时间、电量、信号的那一条）下面。这时候需要给内容加上状态栏高度的顶部内边距，否则时间电量会和你的标题文字叠在一起。获取状态栏高度的标准方式是uni.getSystemInfoSync().statusBarHeight，单位是 px，若你的样式体系以 rpx 为主，需要做一次换算。

App 端还有一个页面级配置字段值得知道：在pages.json的页面配置里可以设置app-plus下的titleNView，把它写成false也能隐藏原生导航栏，这个方式和navigationStyle: custom效果接近，但navigationStyle是跨端的统一写法，优先用它，能少写一份配置。titleNView更适合需要在 App 端对导航栏做细粒度定制（比如只保留背景、嵌入原生搜索框）的场景，属于进阶用法。

2.3 H5 端：浏览器不认这套配置，但表现最省心

H5 端的情况相对简单：navigationStyle: custom在 H5 上同样生效，页面会去掉那层模拟的导航栏。但浏览器本身的地址栏、标签栏是页面无法控制的，所以 H5 端的"沉浸式"天花板由浏览器决定，你在页面内部做自定义头部时，不需要考虑胶囊按钮（没有），也基本不需要考虑状态栏高度（statusBarHeight在 H5 上通常返回 0 或不可靠）。

这个差异直接决定了工程实践里的一条原则：自定义导航栏组件必须按端做条件处理，用条件编译把三套逻辑隔离开，而不是写一堆if混在一起。下面这张表把关键差异集中对比一下，方便你在动手前先想清楚要处理哪些分支。

2.4 只想去掉标题、保留高度的取巧方案

不是所有场景都需要整套自定义导航栏。有些页面只是不想要那行白色标题文字，但希望保留系统返回按钮和整条背景，这时候动navigationStyle反而给自己加活。可行的做法是把navigationBarTitleText设为空字符串，配合navigationBarBackgroundColor设为与页面背景一致的颜色，视觉上就像没有导航栏，但返回逻辑、高度占位全部交给系统，最省事。

提示：这种方案下如果页面是二级页，返回箭头还在，属于"看起来没有导航栏但实际有"的状态。设计评审时一定要跟设计方确认清楚，避免上线后被指出"返回按钮怎么还在"。

3. 把配置落到 pages.json：全局与页面的作用顺序

真正动手时，第一个要做的决定是：这个改动是只作用于某一个页面，还是整个应用统一。这个决定直接反映在配置写在哪一层。

3.1 全局隐藏与单页覆盖的正确写法

全局统一隐藏，写在pages.json的globalStyle里：

{ "globalStyle": { "navigationStyle": "custom", "navigationBarTextStyle": "black" }, "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } } ] }

这样所有页面默认都是自定义导航栏状态。如果某个页面反而需要恢复原生导航栏（比如一个内嵌的协议页，你想要系统标题和返回），就在那个页面的style里显式写回：

{ "path": "pages/agreement/agreement", "style": { "navigationStyle": "default", "navigationBarTitleText": "用户协议" } }

反向的场景更常见：全局保持默认，只让个别页面自定义。那就只在那个页面的style里加"navigationStyle": "custom"。我在项目里更倾向后者，因为默认行为越接近系统原生，出问题时越容易定位，而且全局custom意味着每个新页面都要记得挂自定义导航栏组件，漏一个就是页面内容被状态栏压住，这种低级缺陷在多人协作里防不住。

3.2 条件编译在 pages.json 里的写法

pages.json虽然是个 JSON 文件，但 uni-app 支持在里面写条件编译注释，这点很多人不知道，导致他们为了让不同端有不同配置，去写多份配置文件再手动切换，非常原始。正确写法是在页面style里按平台拆分配置块：

{ "path": "pages/detail/detail", "style": { "navigationBarTitleText": "详情", // #ifdef APP-PLUS "navigationStyle": "custom", // #endif // #ifdef MP-WEIXIN "navigationStyle": "custom", // #endif "navigationBarBackgroundColor": "#ffffff" } }

注意条件编译的注释必须用//，且#ifdef与#endif成对出现。这块最典型的翻车方式是注释符号写错或者嵌套错位，编辑器不会报语法错误，但编译后的配置会缺字段，表现为"某端配置莫名其妙不生效"。改完一定要去编译产物里确认（开发工具一般能在编译后的app.json/pages.json输出中看到扁平化结果）。

注意：pages.json里所有键值必须严格符合 JSON 语法（除了条件编译注释），多一个逗号、少一个引号都会让整个配置解析失败，症状是页面全部变成默认导航栏，而不是报错。遇到"配置好像全丢了"，先检查 JSON 合法性。

3.3 全局自定义后，那些"顺手"的 API 会失效

隐藏原生导航栏之后，一批依赖原生导航栏的 API 会变成空操作，这个连带影响必须在方案评审阶段就说清楚，否则后续需求会撞墙。具体包括：

• uni.setNavigationBarTitle：想改导航栏标题，原生栏没了，自然无效。要在自定义导航栏里换成数据驱动，用ref或状态管理控制标题文本。
• uni.setNavigationBarColor：同样无效。
• uni.showNavigationBarLoading与uni.hideNavigationBarLoading：无效，下拉刷新或请求中的 loading 要自己在页面里实现。
• uni.setNavigationBarTitle在小程序端custom模式下仍可能修改"页面标题"（比如用于分享卡片），但不会显示在界面上，不要指望它做视觉反馈。

我在项目里遇到过这样一个情况：一个列表页原本靠setNavigationBarTitle动态显示"共 N 条"，改成自定义导航栏之后标题一直是静态的，测试同学报了个"数据不更新"的缺陷，其实根子在导航栏方案变更。处理方式很朴素——把标题文本提升到页面 data 里，自定义组件通过 props 接收，逻辑链路清晰可查。

4. 自绘导航栏的组件结构与高度计算

配置改完只是把原生栏拿掉，页面顶上会空出一块或者内容直接顶到状态栏，视觉上并不完整。真正让页面"看起来对"的，是自绘导航栏这一层。这一节讲怎么把它做得能复用、高度算得准。

4.1 组件拆解：状态栏占位、内容区、右侧留白

一个能跨端跑的自定义导航栏组件，结构上应该分成三块：状态栏占位区（只有高度，无内容）、内容区（标题、返回按钮、右侧操作位）、右侧安全留白（小程序端给胶囊让位）。用view嵌套就能实现，核心不在结构而在高度变量的来源。

组件暴露的核心参数建议就三个：title（标题文本）、showBack（是否显示返回按钮）、bgColor（背景色，用于透明渐变场景）。内部高度通过计算属性得到，按端分支：

export default { data() { return { statusBarHeight: 0, navBarHeight: 44, capsuleSpace: 0 }; }, created() { const sys = uni.getSystemInfoSync(); // #ifdef APP-PLUS this.statusBarHeight = sys.statusBarHeight || 0; // #endif // #ifdef MP-WEIXIN const menu = uni.getMenuButtonBoundingClientRect(); this.statusBarHeight = menu.top; this.navBarHeight = (menu.top - sys.statusBarHeight) * 2 + menu.height; this.capsuleSpace = sys.windowWidth - menu.left; // #endif // #ifdef H5 this.statusBarHeight = 0; this.navBarHeight = 44; // #endif } };

小程序端那行navBarHeight的算法是：胶囊上下间距各一份，加上胶囊自身高度。因为胶囊垂直居中在导航栏内容区里，所以内容区高度等于上面留白 + 胶囊高 + 下面留白，而上下留白基本对称。这个推导比直接拍一个 44 靠谱得多，尤其在小屏机上差异明显。

4.2 页面内容如何避开导航栏

导航栏组件定位方式有两种选择，各有代价，需要按页面内容形态决定。

第一种是固定定位 + 提前占位：导航栏用position: fixed; top: 0; left: 0; right: 0; z-index: 99，然后在页面内容容器的顶部加一个等高的padding-top。优点是导航栏始终吸顶，长列表滚动到哪都可见；缺点是那个占位高度必须和组件的实际高度严格一致，一旦两端高度计算不一致，就会出现内容顶部被压或者出现一条缝隙。解决办法是在父页面也用同一套高度计算逻辑，或者把高度通过event或provide/inject传出去。

第二种是正常文档流：导航栏不固定，跟着页面一起滚。适合内容很短、不需要吸顶的场景（比如一个表单页）。实现简单，没有高度同步问题，但滚动体验差一些。

我自己的偏好是：列表类、详情类页面用固定定位，表单类、弹窗较多的页面用文档流。还有一类特殊场景——顶部要做透明渐变（滚动时导航栏背景从透明渐变成白色），这种只能用固定定位，并且要监听onPageScroll动态改透明度，透明度阈值建议在 0 到 60px 的滚动区间内完成过渡，太短会显得突兀。

提示：使用fixed定位时，z-index要给足（99 或 999），但不要给到9999这种量级，否则会和弹窗层级打架。项目里最好统一规划一套层级规范，导航栏、下拉菜单、全屏弹窗、轻提示各自一层。

5. 排查"配置改了却没生效"的完整链路

这是本篇最想重点讲的部分。navigationStyle: custom写进pages.json之后没生效，原因五花八门，但排查路径是可以标准化的。我按自己实际排查的顺序列一遍，遇到问题时从上往下走，一般前三步就能命中。

5.1 第一层：配置有没有被真正编译进去

第一步永远不是怀疑代码，而是确认配置是否进入了构建产物。开发工具保存pages.json后，编译产物里的页面配置会更新，但只有重新编译才保证。常规操作是：停止运行，重新执行编译，App 端建议直接清缓存重启。真机调试时尤其要注意，手机上的基座可能缓存了旧配置，重新运行一次比反复改代码更有效。

如果重新编译后仍然不生效，打开编译输出目录，找到对应平台的配置文件（小程序端是app.json，App 端是manifest相关的合并结果），搜索页面路径，看navigationStyle是否在里面。不在这里面，就说明配置写的地方不对——最常见的是把style写在了pages数组外面，或者页面path与实际路径大小写不一致（注意：某些平台对路径大小写敏感），导致配置没有匹配上任何页面。

5.2 第二层：页面是不是被别的机制接管了

配置确实在产物里，但页面还是不按预期显示，这时候要怀疑"接管"。几种典型情况：

• 页面用了自定义组件套壳，比如uni-nav-bar这类第三方导航组件，它们内部会自己渲染一层，如果同时配置了custom，可能出现二层叠加，看起来像"没隐藏"。这种情况要检查页面根节点结构，去掉多余的导航组件。
• 项目里引入了全局布局组件（比如通过easycom自动注入的公共头部），它在每个页面顶部渲染，与navigationStyle无关，但视觉上等效于一条导航栏。判断方法是临时把该组件注释掉，看页面顶部是否变化。
• 条件编译写反了，#ifdef APP-PLUS写成了#ifndef APP-PLUS，导致目标端配置被排除。这种错误在小项目里出过不止一次，改完顺手检查注释块是否成对、平台名是否拼写正确（APP-PLUS、MP-WEIXIN、H5是标准写法）。

5.3 第三层：高度对了但视觉不对

配置生效、导航栏消失，但页面内容被状态栏压住，或者顶部出现一条空白。这类问题不是"没生效"，而是高度计算错位，症状和配置错误很像，容易误判。

先判断是哪一端：App 端出现内容顶到最上方，九成是没加statusBarHeight；小程序端出现内容和胶囊重叠或者标题偏上，是胶囊位置没取对；H5 端出现多余空白，多半是给statusBarHeight赋了一个非 0 值。排查手段是把计算出来的高度变量直接渲染到页面上看（临时加一行文本显示数值），比在脑子里推演快十倍。

还有一类隐蔽情况：页面本身有padding-top，自定义导航栏也有固定高度占位，两者叠加导致内容下移过多。这时要检查页面根容器的样式，尤其是从老页面复制过来的代码，往往带着历史遗留的padding。

5.4 第四层：下拉刷新与滚动行为被改变

隐藏原生导航栏后，一个非常容易被忽略的连带变化是下拉刷新区域。小程序端的原生下拉刷新在某些配置下依赖导航栏布局，改成custom后可能出现下拉区域错位、或者自定义导航栏跟着一起下拉的怪异现象。App 端如果开启了pullToRefresh，同样可能出现刷新指示器位置不对。

处理思路是把下拉刷新的触发区域显式限定在内容列表上，而不是整页。用scroll-view承载列表，配合refresher-enabled系列属性，控制权会清晰很多。如果坚持用页面级下拉刷新，就要接受导航栏可能跟着位移的视觉表现，或者干脆把导航栏做成固定定位，让它脱离滚动容器。

注意：这一层的问题在开发机上往往复现不了，必须真机验证，而且最好在低端机上验一遍。滚动相关的表现对性能敏感，模拟器和真机差异很大。

把这条链路走完，基本能覆盖 95% 以上的"配置不生效"场景。梳理下来会发现，真正因为 uni-app 框架本身出问题的概率极低，绝大多数是配置层级、编译缓存、条件编译、高度计算这四类原因。养成"先看产物、再看结构、最后看计算"的顺序，排查效率会比瞎试高很多。

6. 几个容易引发返工的设计细节

方案跑通之后，还有一些细节决定了这套东西能不能在项目里长期用下去。这部分偏经验，都是实际项目里踩出来的。

透明导航栏与内容穿透。很多设计稿要求导航栏背景透明、内容从图片上"浮"过去，滚动到一定距离才变成白色。实现时导航栏背景设成透明只是第一步，还要注意页面内容的第一屏顶部要预留导航栏高度，否则图片顶部的内容会被导航栏文字盖住。正确的做法是图片容器撑满整屏并在内部用padding-top让出安全区，导航栏叠在最上层。这套结构在小程序端还要额外处理胶囊的对比度问题——图片颜色浅的时候，白色胶囊按钮里的图标可能看不清，这时候要么给图片加一层半透明遮罩，要么在胶囊后面放一个深色胶囊形状的底。

物理返回键与手势返回。App 端和小程序端隐藏原生导航栏后，系统的返回手势依然可用，但页面里的自绘返回按钮如果和手势逻辑不一致，会出现"点按钮退一层、滑手势退两层"的情况。原因是自绘按钮里调了navigateBack，而手势本身也会触发一次。这类问题通常出现在按钮事件没有做防抖、或者页面栈里有重定向操作时。检查方法是在onBackPress（App 与部分小程序支持）里打日志，看一次返回触发了多少次。

页面栈与导航栏标题的同步。自定义导航栏的标题如果是从路由参数里取的，要注意页面被navigateBack返回后重新展示时，标题是否需要刷新。这类"看起来是导航栏问题、实际是页面生命周期问题"的缺陷，排查起来最费时间。

多端样式一致性验收清单。上线前建议固定走一遍这份清单，能挡掉大部分低级问题：

别为了统一而过度抽象。有些团队会把自定义导航栏做成一个极度通用的组件，塞进去几十个 props，覆盖搜索框、tab、多级标题各种形态。短期看很整齐，长期看每次需求变更都要动这个公共组件，回归范围巨大。我的建议是：把高度计算和基础布局抽成公共能力（这部分最容易出错、最值得统一），把内容区留给各页面自己写。这样既能保证顶部安全区的算法一致，又不会让组件变成难以维护的巨物。这个取舍在实际项目里被验证过多次，公共能力越薄，演进越轻松。

最后说一个很实际的体会：这类"配置 + 布局"的问题，文档里通常只有一行字段说明，真正的坑全在跨端差异和高度计算上。所以在项目初期就把三端表现各截一张图存档，后面有人问"为什么小程序这里多一块"的时候，翻图比翻代码快。