企业官网建设流程全解析

如果你写过一段时间微信小程序，大概率会有这样的体感：业务逻辑写起来反而顺畅，真正让人挠头的经常是页面配置。特别是当项目从单页 demo 长成多页面应用后，一个导航栏标题、一个 tabBar 图标、一个 usingComponents 路径，都能在上线前给你来一次突然袭击。我见过不少项目挂在“页面路径未找到”，也见过自定义导航栏适配到一半，结果真机上一跑，标题直接怼进刘海屏。

这篇文章就把微信小程序的页面配置完整拆一遍。不会只丢出一份配置代码，而是把每个字段为什么这样写、哪些配置容易踩坑、真机和开发者工具表现有什么差异都讲清楚。适合刚入门的新手按顺序读，也更适合已经上线过几个小程序、想系统性排查页面配置隐患的开发者对照检查。

1. 页面配置中最容易忽略的分层规则：app.json 与页面 json 到底谁说了算

1.1 全局配置的默认值从哪里来

微信小程序的页面配置，本质上是两层配置文件的叠加：全局的 app.json 和每个页面目录下的 .json 文件。很多人第一次接触时，容易把 app.json 理解成“全局样式表”，但它更准确的定位是“全局窗口配置默认值”。项目创建时，默认的 app.json 里通常长这样：

{ "pages": [ "pages/home/index" ], "window": { "navigationBarTitleText": "首页", "navigationBarBackgroundColor": "#ffffff", "navigationBarTextStyle": "black", "backgroundColor": "#f5f5f5", "backgroundTextStyle": "light" } }

其中 window 字段下的配置，就是所有页面在没有单独写页面配置时的默认表现。它管的是导航栏标题、导航栏背景色、导航栏文字颜色、窗口背景色这些全局外观。换句话说，页面 json 如果什么都不写，页面也会老老实实套用 window 里的这套默认值。

这里我要特别强调一个概念：页面 json 并不是 app.json 的替代品，而是按字段级别的覆盖。它不是一个独立的窗口配置，更像是一个针对当前页面的“修正补丁”。理解这一点，后面很多诡异问题都能找到根因。

1.2 页面配置覆盖全局配置的判断顺序

我见过一个真实案例：团队在 app.json 里把导航栏背景色设置成深色，文字颜色设置成白色。后来某个页面需要独立主题，于是页面 json 只写了一个 navigationBarBackgroundColor 为橙色。结果真机测试时，这个页面的导航栏文字变成了黑色。原因很简单——页面 json 只覆盖了背景色，没有覆盖 navigationBarTextStyle。而全局配置里的 white 是建立在深色背景这个前提下的，一旦当前页面背景被替换成浅色，white 不再适用，系统就采用了默认的 black。

这种“按字段合并”的机制，带来的问题不是配置不生效，而是配置“部分生效”后表现不符合预期。所以我在实际工程里的建议是：如果一个页面需要彻底独立的窗口表现，索性把导航栏相关的五个字段一起写完整。

{ "navigationBarTitleText": "活动详情", "navigationBarBackgroundColor": "#ff6600", "navigationBarTextStyle": "white", "backgroundColor": "#ff6600", "backgroundTextStyle": "light" }

不要图省事只写差异。虽然从官方文档的逻辑看，按字段合并是成立的，但不同基础库版本对某些字段的默认行为有细微差异，写完整能减少真机上的意外。

另外，tabBar、pages、networkTimeout 这类配置只能在 app.json 里写，页面 json 改了也没用。如果你发现某个页面 json 里配了 tabBar 相关的字段，基本可以断定这个写法是无效的。页面 json 能控制的，主要就是窗口表现、组件引用、页面下拉、滚动这类和当前页面强相关的内容。

2. 导航栏区域配置：从默认标题到自定义导航的适配细节

2.1 navigationBarTitleText 的字符数和动态标题的配置

导航栏标题是页面配置里出镜率最高的字段。如果标题是固定的，直接在页面 json 里写 navigationBarTitleText 就行。但业务里大量标题是动态的，比如详情页要展示文章标题、商品名称，不可能提前写到 json 里。

动态标题需要用 wx.setNavigationBarTitle 在页面逻辑里设置。我一般放在 onLoad 里同步调用。这里有个小坑：如果标题依赖接口数据，页面会先显示默认标题，接口返回后再 setNavigationBarTitle，视觉上会闪一下。要减少这种闪烁，可以提前把默认标题设置成空字符串，或者用一个通用标题占位，请求回来后再替换。

标题长度也要注意。navigationBarTitleText 显示不下时，系统会截断并显示省略号，但不同机型的截断位置不一样。iOS 和 Android 对中英文混排的截断表现也有差异。如果标题是用户生成的长文本，最好在代码侧先裁切到 12～15 个中文字符。别指望系统帮你优雅省略，它只会粗暴地“一刀切”。

2.2 自定义导航栏与顶部胶囊按钮的避让

navigationStyle: "custom" 是页面配置里的重头戏。配置之后，页面内容会直接延伸到屏幕顶部，不再保留系统导航栏。这个能力给了 UI 设计很大的自由度，但也把状态栏高度、胶囊按钮位置这些原本系统处理好的问题，全部抛给了开发者。

很多人第一次做自定义导航栏时，习惯在页面上写一个固定 padding-top: 64px。这个数值在部分机型上看起来没问题，但一到带刘海的全面屏，页面标题就会往上顶，甚至和胶囊按钮重叠。原因很简单：不同机型的状态栏高度不同，胶囊按钮距离状态栏的间距也不同。

正确做法是动态读取两个值：

• statusBarHeight，可以通过 wx.getWindowInfo().statusBarHeight 获取
• 胶囊按钮位置，通过 wx.getMenuButtonBoundingClientRect() 获取

拿到这两个值后，自定义导航栏的高度可以这样算：胶囊按钮的底部位置加上它和状态栏之间的间距，或者直接取 menuButtonBounding.bottom 加上一个固定留白。很多组件库封装的 useCustomNavigation 之类 hook，原理就是这一套，只是把计算过程封装好了。

关键点在于：不要在页面 json 里写死任何像素值。自定义导航栏的高度必须来自真机运行时读取的数据。尤其是折叠屏和不同尺寸 pad，状态栏高度差异很大，写死数值一定会出问题。

2.3 自定义导航后页面的安全区处理

自定义导航栏不只是顶部的问题。页面底部在 iPhone 全面屏机型上还有 home indicator 安全区，如果底部有操作栏、输入框，也要手动适配。WXSS 里可以用：

padding-bottom: env(safe-area-inset-bottom);

很多新人在做自定义导航栏时，只关注顶部，忽略了底部。真机一跑，底部的“确认支付”按钮被导航条挡住一半，非常影响体验。

还有一个细节：自定义导航栏页面如果开启下拉刷新，下拉时露出的背景色取的是 window.backgroundColor，而不是页面根节点的背景色。这个背景色在 app.json 里配置。如果你只在页面根节点 WXSS 里设置了背景色，下拉时会发现露出来的区域颜色不一致。我习惯把所有自定义导航栏页面的 window backgroundColor 统一设置成和导航栏背景一致，这样下拉时视觉上是连续的。

3. 页面路由与启动路径配置：pages 数组、tabBar 和外部链接

3.1 pages 数组顺序与小程序启动页的关系

app.json 的 pages 数组不仅是一个页面清单，它第一项决定了小程序的启动页。很多项目里，pages 数组的顺序并不等于业务导航顺序，但第一页一定是启动后第一个展示的页面。

这个顺序调整有个隐藏坑：在微信开发者工具里，如果你保存过某个“编译模式”，修改 pages 数组顺序后，工具可能还在按旧的编译模式启动。表现就是：明明把首页地址改到数组第一位了，点编译还是进入老页面。这时候需要检查编译模式里的启动页面是否同步修改，或者直接重置回普通编译。

pages 数组里的路径都不能带后缀名，比如 "pages/home/index"，不要写成 "pages/home/index.js" 或 "pages/home/index.json"。这个错误在新手项目里经常出现，编译时直接报错。另外，路径大小写必须和文件系统一致。Windows 上的开发者工具对大小写不敏感，但真机 iOS 敏感，所以千万不要以为本地能跑就万事大吉。

3.2 tabBar 配置的图标限制和选中态

tabBar 是小程序底部导航的配置块，只能写在 app.json 里，页面 json 管不到。最少 2 个 tab，最多 5 个。配置结构大致是：

{ "tabBar": { "color": "#999999", "selectedColor": "#ff6600", "backgroundColor": "#ffffff", "borderStyle": "black", "list": [ { "pagePath": "pages/home/index", "text": "首页", "iconPath": "assets/tab-home.png", "selectedIconPath": "assets/tab-home-active.png" } ] } }

iconPath 和 selectedIconPath 有两点经常被忽略。第一，图片必须是本地路径，不支持网络图片；第二，官方建议图片尺寸是 81px * 81px。如果图标切图尺寸不规范，真机上可能看起来发虚，尤其是非 2 的倍数尺寸。字体图标在 tabBar 里也没法直接用，必须先把字体渲染成 PNG，再放到 assets 目录里。

borderStyle 这个字段只支持 black 和 white，不能自定义其他颜色。如果你想让 tabBar 顶部有一条浅灰色分割线，只靠 borderStyle 做不到。我在项目里是直接把 tabBar 的 backgroundColor 调成浅灰，视觉上做出分割线的效果。这个限制文档里写得比较隐晦，实际遇到的开发者挺多。

3.3 h5 链接跳小程序时的页面路径配置

h5 页面唤起微信小程序时，通常要配置一个 path 参数。这个 path 必须和 app.json 里的页面路径完全一致。常见问题是跳转后提示“页面不存在”或“无法访问”，排查时先看两件事：路径是否真的在 pages 数组里，路径中的查询参数是否正确编码。

如果 path 里带中文或特殊字符，一定要用 encodeURIComponent 处理。比如详情页地址是 pages/detail/index?id=100，看起来没问题，但 id 换成商品名称“秋冬新款外套”后，没有编码就会导致跳转失败。

还有一个更稳妥的做法是：h5 链接不要直接跳业务页面，而是跳一个统一的“中转页面”。中转页面在 onLoad 里解析参数，再用 wx.redirectTo 或 wx.switchTab 分流。这样做的好处有三个：一是避免外部链接把参数直接暴露给业务页面；二是可以在中转页做埋点统计；三是如果目标页面是 tabBar 页面，可以在中转页里统一判断跳转方式，因为普通页面跳 tabBar 页面必须用 wx.switchTab，而外部链接本身不关心页面栈规则。

4. 组件按需引入与样式隔离：页面 json 中 usingComponents 的正确写法

4.1 usingComponents 局部注册与全局注册的取舍

页面 json 里的 usingComponents 字段，是小程序组件化开发的核心配置。它的作用是在当前页面注册自定义组件，注册后才能在 wxml 里使用对应标签。

很多项目图省事，把常用组件放到 app.json 里全局注册。全局注册确实方便，但副作用是：所有页面都会把组件代码打入主包。微信小程序主包有大小限制，一旦超过，上传发布都成问题。我见过一个项目，只在某一个页面用了一次日历组件，却因为图方便全局注册，主包体积涨了快 1MB。

我的建议是：组件尽可能在使用它的页面里局部注册。特别是弹窗、日历、图表这类体积较大的业务组件。全局注册只适合那些几乎每个页面都会用到的极小功能性组件，比如一个纯展示的 tag 标签。

局部注册的写法如下：

{ "usingComponents": { "custom-dialog": "/components/custom-dialog/index", "price-tag": "/components/price-tag/index" } }

这里推荐使用绝对路径，也就是以 / 开头，相对于小程序根目录。很多同学习惯写相对路径 ../components/xxx，一旦页面目录层级调整，整个组件引用全部失效，编译时才报错。绝对路径虽然写起来稍长，但胜在稳定，不会因为目录结构调整而突然断裂。

4.2 组件样式隔离导致的自定义单选框等表单控件问题

自定义组件默认是样式隔离的，页面 WXSS 里的选择器不会侵入组件内部。这个机制本意是好的，但实际开发中经常带来困惑：明明在页面里写了 .custom-radio { color: red }，组件内部却纹丝不动。

要理解这个机制，得先认识 styleIsolation 字段。页面 json 里可以这样配置：

{ "usingComponents": { "custom-radio": "/components/custom-radio/index" }, "styleIsolation": "apply-shared" }

styleIsolation 有三个可选值：

• isolated：完全隔离，页面样式对组件无效，组件样式也不会影响页面
• apply-shared：页面样式会影响组件，但组件样式不会影响页面
• shared：页面和组件样式双向影响

这里的 apply-shared 经常被误解，它指的是页面 WXSS 会“应用于共享样式”，而不是组件样式会应用到页面。简单记就是：apply-shared 是单方向的，页面可以影响组件，组件不能影响页面。

如果你在做自定义单选框、复选框这类表单控件，遇到改样式改不动的情况，先别急着加 !important。检查一下组件内部是否设置了 styleIsolation，以及它用的是原生节点还是虚拟节点。虚拟节点情况下，外部样式覆盖需要借助 externalClasses 机制，这是自定义组件里专门用来开放样式入口的配置。正确的做法是：组件通过 properties 接收 checked 等状态，外部只传数据，不直接修改组件内部节点样式。这样既绕开了样式隔离，也保持了组件封装性。

还有一个和 usingComponents 相关的坑：小程序有“按需注入”优化，在 app.json 里配置 "lazyCodeLoading": "requiredComponents" 后，组件代码会按需注入。这个优化对性能是好事，但副作用是：页面 json 里漏注册组件的影响会被放大。漏注册的组件不会注入代码，页面渲染时可能直接空白或者告警。所以开了按需注入之后，必须确保所有用到的组件都在 usingComponents 里声明了。

5. 网络请求相关的页面配置：超时、合法域名与统一请求封装

5.1 networkTimeout 全局设置和它的真实表现

app.json 里有一个 networkTimeout 配置块，很多新项目根本没注意到它：

{ "networkTimeout": { "request": 15000, "connectSocket": 15000, "uploadFile": 60000, "downloadFile": 60000 } }

如果不配置，request 的默认超时是 60 秒。60 秒是什么概念？用户在弱网环境里打开一个页面，看到菊花转圈整整一分钟，然后才等来“请求超时”。这个体验是非常糟糕的。我一般会把 request 超时配成 15 秒左右。

但这里要说明白：networkTimeout 只是客户端发起请求的超时时间，不是服务端处理时间的上限。如果后端接口本身就要执行 20 秒，你把客户端超时设成 10 秒，结果就是“误杀”。遇到这种接口，正确做法是让后端改成异步任务，前端先拿到一个任务 ID，再轮询查询任务状态，而不是无限加大超时。

合法域名也是网络配置的一部分。生产环境下，request、uploadFile、downloadFile、connectSocket 的域名都需要在小程序后台配置白名单。开发阶段可以在开发者工具里勾选“不校验合法域名”，但这只方便本地调试。真机预览时，如果白名单没配，请求一样失败。页面配置在这里的角色是兜底：networkTimeout 只是一个默认值，实际请求时可以在 wx.request 里单独传 timeout 覆盖。我建议请求封装层统一显式传入超时时间，不依赖全局配置，这样某个接口需要特殊超时时间时，处理起来更灵活。

5.2 请求封装如何读取页面路径和业务上下文

页面配置和请求封装的联动，经常被忽略的一点是：请求打出去时，后端不知道请求是从哪个页面发出的。排查线上问题时，如果日志里只有接口 URL，没有页面上下文，定位问题会非常费劲。

利用页面路由栈，可以拿到当前页面路径：

const pages = getCurrentPages() const currentPage = pages[pages.length - 1] const route = currentPage ? currentPage.route : ''

这里的 route 就是 app.json 里配置的页面路径，比如 pages/order/index。请求拦截器统一把这个字段塞进请求 header 或 body，后端日志就能直接看出是哪个页面发起的请求。这个信息在排查“用户反馈某个页面接口报错”时特别有用。

请求封装里还有一个细节和页面配置强相关：处理登录态过期。接口返回 401 时，通常要引导用户重新登录。但跳转登录页不能一刀切——如果当前页面是 tabBar 页面，用 wx.navigateTo 是跳不过去的，必须用 wx.switchTab 先跳到登录入口页，或者用 reLaunch 重启动到登录页。判断当前页面是否 tabBar 页面，本质上也和 app.json 里 tabBar 配置相关。如果项目里 tab 页面比较多，可以在封装层统一维护一个 tabBar 路径白名单，避免每次跳转都判断失误。

5.3 uniapp 多端开发时的页面配置差异

用 uniapp 开发微信小程序时，页面配置会多一层转换。uniapp 的 pages.json 负责管理页面路由和样式，但它并不能完整覆盖微信原生页面 json 的所有能力。

一个典型差异是 navigationStyle: "custom"。在 uniapp 里，可以在 pages.json 中某个页面的 style 节点下配置：

{ "path": "pages/detail/index", "style": { "navigationStyle": "custom" } }

这个配置在微信小程序端会生效，但在 H5 端不会。H5 端没有微信小程序的导航栏概念，你在 pages.json 里写了 navigationStyle，H5 端可能完全无视，而是继续用浏览器标签标题。

多端项目特别容易遇到“双导航栏”问题：H5 端浏览器顶部有一个标题栏，页面顶部又自己画了一个模拟导航栏，看起来像个叠叠乐。解决方案是用条件编译，只在微信小程序端启用自定义导航：

// #ifdef MP-WEIXIN { "navigationStyle": "custom" } // #endif

这样同一份 pages.json 在不同端编译时，行为才会符合预期。多端项目的页面配置，核心原则就是“不要相信一份配置能通吃三端”。微信小程序、App、H5 各自的导航体系和页面生命周期都有差异，配置本身就需要分开维护。

6. 页面配置常见报错与调试经验：从白屏到路径找不到

6.1 “页面路径未找到”的排查链路

这是小程序开发里最常见的报错之一。报错信息很直白：“页面路径未找到”。但触发原因至少有三种：

1. app.json 的 pages 数组里没有注册这个页面
2. 页面目录里缺少对应的 .json 文件，或者文件名拼写错误
3. 路径大小写不一致

前两种比较好理解，第三种要单独拿出来说。Windows 开发者工具对路径大小写不敏感，很多开发者因为长期在 Windows 上开发，习惯性地忽略大小写问题。但真机 iOS 对路径大小写敏感，本地编译通过不代表真机没问题。所以排查这个报错时，不要只盯着 app.json 看，还要去文件系统里确认实际目录名的大小写。

如果项目已经跑了很久突然报“页面路径未找到”，先想想最近是不是移动过文件、改过目录名。移动目录后，如果只改了文件系统里的位置，没有同步修改 app.json 和页面 json 里的 usingComponents 相对路径，就会出现这种怪问题。

6.2 编译模式、热刷新与配置缓存的冲突

微信开发者工具有热刷新功能，平时改代码保存后页面会自动刷新。但页面配置改完之后，经常会有不生效的情况。最典型的场景是：在 app.json 里改了 tabBar 图标，页面却还是显示旧图标。

这是因为热刷新对全局配置的响应并不可靠，尤其 tabBar 这种和原生渲染层挂钩的配置，必须整包重新编译才会重建。遇到配置不生效，不要急着怀疑代码没保存，先按 Ctrl+Shift+R 清缓存重新编译，多半就好了。

还有一个容易被忽略的配置字段：disableScroll。这个字段在页面 json 里配置为 true 时，页面本身不能下拉滚动。但它只影响页面级滚动，不影响 scroll-view 组件内部的滚动。如果你发现整个页面不能滚动了，检查是不是在页面 json 里误开了 disableScroll，而不是在 WXSS 里找 overflow 的毛病。

页面 json 里的配置改动，有时不会立即热更新到模拟器。我现在的习惯是：改完一个页面的 json 配置后，手动点一次编译按钮，然后观察 console 日志里有没有对应的编译报错。这一步虽然简单，但能省下不少“配置不生效”的排查时间。

6.3 一个页面配置自检清单

把这一路摸过的坑整理成清单，每次新页面提交前，可以照着过一遍：

• 页面路径是否已加入 app.json 的 pages 数组，大小写是否和实际目录一致
• 页面 json 是否存在，窗口字段是否写完整
• 自定义导航栏页面是否处理了状态栏高度和胶囊按钮避让
• 是否配置了 styleIsolation，组件样式是否有意被页面控制
• 用到的自定义组件是否都在 usingComponents 里注册
• 是否配置了 networkTimeout，或每个请求是否显式传入超时时间
• tabBar 目标页面跳转时是否使用 wx.switchTab
• 底部操作栏是否处理 env(safe-area-inset-bottom)
• 生产环境域名白名单是否已添加对应域名

这个清单很朴素，但我靠它减少了不少上线前的低级问题。页面配置不像业务逻辑那样能靠单元测试覆盖，它更多是环境相关的东西，真机上的表现和开发者工具经常有差异。建议每次发版前，至少在 iOS 和一部 Android 真机上把主要页面过一遍。

一个小技巧：如果你经常要在一堆页面 json 里找某个配置，可以全局搜索配置字段，不要一个个文件点开看。开发者工具支持整个项目目录搜索，搜 navigationStyle、usingComponents 这类字段，能快速定位所有自定义导航栏页面和组件引用情况。页面配置太多了之后，这种方式比人肉翻目录高效得多。