【微信小程序问题解决】微信小程序全局 navigationBarTitleText 不起作用

问题描述：

微信小程序开发中，明明在 app.json 的 window 配置里写了 "navigationBarTitleText": "我的应用"，为什么进入首页后标题依然是默认的"微信小程序"，或者在跳转页面后标题没有按预期变化？

app.json 示例：

{
  "pages": [
    "pages/index/index",
    "pages/detail/detail"
  ],
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "全局标题" 
  }
}

编译运行，发现首页标题根本不是"全局标题"。

问题原因：

1. 页面级配置 > 全局配置

微信小程序的设计哲学是：局部优先于全局 。
app.json 中的 window 字段确实是全局默认配置，但如果你的某个页面（比如 pages/index/index）拥有自己的 index.json 文件，并且在这个文件里声明了 window 相关的属性，那么页面级的配置会直接覆盖全局配置。

陷阱： 即使你的 index.json 是一个空对象 {}，在某些低版本基础库或特定编译环境下，也可能打断全局配置的继承。但最常见的情况是，你无意中加了配置：

// pages/index/index.json
{
  "usingComponents": {},
  "navigationBarTitleText": "" // 这里哪怕写了空字符串，也会覆盖全局！
}

2. 自定义导航栏的干扰

如果你在全局或页面配置中设置了 "navigationStyle": "custom"，微信小程序会完全隐藏原生导航栏 。

在这种情况下，navigationBarTitleText 是绝对不起作用的，因为连导航栏都没有了，标题渲染给谁看呢？这时候你需要用 View 和 CSS 自己画一个标题。

3. 动态设置标题的时机问题

在页面逻辑中，我们经常用 wx.setNavigationBarTitle 来动态修改标题。但如果在 onLoad 中发起了异步请求，在请求回调中设置标题，用户看到的往往就是跳变的效果，甚至因为页面销毁导致设置失败。

解决办法：

方案一：严格检查页面级 json 文件（最常见解决办法）

原则： 如果你想用全局标题，千万不要在页面级的 .json 文件中写任何与 window 相关的字段 （如 navigationBarTitleText、navigationBarBackgroundColor 等）。

正确做法：

// pages/index/index.json
{
  "usingComponents": {} 
  // 坚决不写 navigationBarTitleText，让它自动继承 app.json
}

方案二：使用 wx.setNavigationBarTitle 进行动态兜底

如果由于业务需要（比如标题依赖于接口返回的数据），必须动态设置，请确保调用时机，并配合默认标题使用：

// pages/detail/detail.js
Page({
  data: {
    title: '加载中...' // 默认标题
  },
  onLoad(options) {
    // 1. 先立刻设置一个默认标题，防止闪现全局标题
    wx.setNavigationBarTitle({
      title: this.data.title
    });

    // 2. 拿到数据后再更新
    wx.request({
      url: 'xxx/api',
      success: (res) => {
        wx.setNavigationBarTitle({
          title: res.data.name
        });
      }
    });
  }
})

方案三：自定义导航栏场景下的处理

如果使用了自定义导航栏，请放弃 navigationBarTitleText，直接在 WXML 中写死或绑定数据：

<!-- pages/index/index.wxml -->
<view class="custom-nav-bar">
  <text>{{navTitle}}</text>
</view>

💡 避坑指南（进阶技巧）

1. 分包页面的配置继承

小程序的主包 和分包 的配置继承机制有时会让人迷惑。

如果在 app.json 的 subpackages 中通过 root 定义了分包，分包下的页面如果想要统一的标题，最好在分包对应的目录下放一个通用的模板，或者在每个子页面明确写上 .json，不要过度依赖全局配置在分包中的表现。

2. 分享场景下的标题

有时候觉得标题没生效，其实是被分享卡片的配置干扰了视线。

// 分享的标题和导航栏标题是两码事！
onShareAppMessage() {
  return {
    title: '这是分享卡片的标题，不是导航栏标题',
    path: '/pages/index/index'
  }
}

3. 微信开发者工具的 Bug

如果你确认代码写得完美无缺，但开发者工具里就是不生效：

• 清缓存： 点击开发者工具上方"清缓存" -> "全部清除"。
• 重新编译： 有时候热更新对 json 文件的监听不灵敏，手动点一下"编译"。
• 真机调试： 某些低版本工具的渲染层和逻辑层同步存在 Bug，用真机预览一下，很多时候真机是正常的。