写过微信小程序的都知道，app.json 是每个项目的入口配置文件。它管着页面路由、窗口外观、底部导航栏这些核心设置。第一次接触的时候对着文档一个字段一个字段敲，敲错了还不知道哪里出了问题。后来发现其实这个文件的结构不算复杂，搞清楚几个关键字段就行。

pages 字段：页面路由列表

pages 是数组类型，列了项目里所有页面的路径。微信会自动把数组第一个元素当作首页。路径是相对于项目根目录的，不需要加文件后缀。比如：

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs",
    "pages/detail/detail"
  ]
}

这里有个容易踩的坑：路径必须真实存在。如果你在 pages 数组里写了 "pages/about/about" 但实际上没有这个目录和文件，编译器直接报错。另外新增页面之后记得手动把路径加进去，或者用开发者工具的 "添加页面" 功能自动处理。

还有一个细节：子包（subpackages）里的页面不要重复写在 pages 主包里，否则会冲突。

window 字段：窗口外观配置

window 控制的是所有页面默认的顶部导航栏样式和背景色等。常用的有这几个属性：

  • navigationBarTitleText — 导航栏标题文字，比如 "我的小程序"
  • navigationBarBackgroundColor — 导航栏背景颜色，用十六进制值如 #ffffff
  • navigationBarTextStyle — 导航栏标题颜色，只能选 black 或 white
  • backgroundColor — 窗口的背景色，下拉刷新时露出来的那个区域
  • backgroundTextStyle — 下拉 loading 的样式，dark 或 light
  • enablePullDownRefresh — 是否开启下拉刷新，布尔值
{
  "window": {
    "navigationBarTitleText": "示例小程序",
    "navigationBarBackgroundColor": "#059669",
    "navigationBarTextStyle": "white",
    "backgroundColor": "#f5f7fa",
    "backgroundTextStyle": "dark",
    "enablePullDownRefresh": true
  }
}

如果某个页面想单独覆盖这些默认值，可以在对应页面的 .json 文件里单独声明 window 属性，优先级高于 app.json。

tabBar 字段：底部标签栏

tabBar 配置底部 tab 切换菜单。最少 2 个，最多 5 个 tab。list 数组里每一项需要 pagePath（页面路径）、text（显示文字）、iconPath（图标路径）和 selectedIconPath（选中后的图标路径）。图标必须是本地图片，建议尺寸 81×81 px。

{
  "tabBar": {
    "color": "#999",
    "selectedColor": "#059669",
    "backgroundColor": "#fff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/home.png",
        "selectedIconPath": "images/home-active.png"
      },
      {
        "pagePath": "pages/profile/profile",
        "text": "我的",
        "iconPath": "images/user.png",
        "selectedIconPath": "images/user-active.png"
      }
    ]
  }
}

tabBar 的 iconPath 经常出问题——图片路径不对、用了网络地址、或者文件根本不存在。遇到 tabBar 不显示的情况，先检查这几点。

其他常用字段

networkTimeout 设置各种网络请求的超时时间（毫秒），包括 request、connectSocket、uploadFile、downloadFile。默认都是 60000ms。

debug 开关，设为 true 会在控制台输出调试信息。开发阶段开着方便排查问题，上线前记得关掉。

permission 用于声明需要用到的权限，比如位置信息 scope.userLocation。

style 设为 v2 可以启用新版组件样式，一般推荐开启。

可视化工具能做什么

手写 JSON 容易漏逗号、拼错字段名、或者忘记某个属性的合法取值范围。可视化配置工具就是把各个字段拆成表单，你填选项它帮你拼 JSON。好处有几个：

  • 不用记每个字段的名字和可选值
  • 实时预览生成的 JSON 内容
  • 减少语法错误（少了括号、多了逗号这类低级失误）
  • tabBar 图标那块可以直观看到结构

跟微信开发者工具自带的 JSON 编辑器比起来，在线工具多了一个优势：可以脱离开发环境快速试配置，适合刚开始搭项目骨架的时候用。不过最终还是要回到项目里验证效果。

app.json 常见报错怎么处理

  • pages 路径不存在：检查文件是否真的在对应目录下，注意大小写敏感
  • tabBar iconPath 找不到文件：确认图片在项目根目录或相对路径正确，且不是网络 URL
  • JSON 解析失败：通常是有多余的逗号、注释（JSON 不支持注释）或中文引号
  • tabBar list 超过 5 个：微信限制最多 5 个 tab，拆分功能到子页面解决
  • navigationBarTextStyle 取值非法：只能是 black 或 white，不能自定义颜色

大部分报错信息在开发者工具的控制台里都能看到具体原因，仔细读一下提示基本能定位问题。

常见问题

app.json 修改后没生效怎么办？

先检查 JSON 语法是否正确——少一个逗号或多一个逗号都会导致整个配置失效。然后在微信开发者工具里点击"编译"重新构建项目。如果还是不行，重启开发者工具试试。常见原因是 JSON 不允许注释，如果你加了 // 注释会直接报错。

tabBar 最多能放几个标签？

tabBar 的 list 数组最少 2 个、最多 5 个标签。超过 5 个会编译报错。如果你需要更多入口，考虑用首页宫格导航或抽屉菜单来替代。

页面路径写错会怎样？

如果 pages 数组里写了不存在的页面路径，编译时不会报错，但用户打开那个页面会白屏。开发阶段可以在开发者工具的 Console 面板看到 404 类型的错误提示。上线前务必检查每个路径都有对应的页面文件。

app.json 生成

使用 app.json 生成工具

相关工具

TabBar 配置生成器
分包配置生成器