微信小程序app.json配置全解析

以下是微信小程序 app.json 文件的完整详解，包括所有配置项说明、可选值、代码示例（含详细注释）、默认新建项目配置项说明，并以表格形式总结关键信息。

—

一、app.json 概述

app.json 是微信小程序的全局配置文件，用于定义页面路径、窗口样式、性能优化、分包策略等。该文件必须位于项目根目录下。

---

二、默认新建小程序的 app.json 配置解析

{
  // 页面路径列表（第一个为启动页）
  "pages": ["pages/index/index"],

  // 窗口表现配置
  "window": {
    // 导航栏标题颜色：black / white
    "navigationBarTextStyle": "black",
    // 导航栏样式：custom 表示使用自定义导航栏
    "navigationStyle": "custom"
  },

  // 启用新版全局样式（v2 支持更好的兼容性）
  "style": "v2",

  // 渲染器类型：skyline 表示使用 Skyline 渲染引擎（支持更现代的 Web 特性）
  "renderer": "skyline",

  // Skyline 渲染器选项
  "rendererOptions": {
    "skyline": {
      // 是否自动将 inline 元素显示为 block
      "defaultDisplayBlock": true,

      // 是否启用 content-box 盒模型
      "defaultContentBox": true,

      // 标签名与样式隔离模式（legacy：兼容旧版）
      "tagNameStyleIsolation": "legacy",

      // 是否禁用 AB 测试（建议上线时开启）
      "disableABTest": true,

      // Skyline SDK 起始生效版本号
      "sdkVersionBegin": "3.0.0",

      // Skyline SDK 结束生效版本号
      "sdkVersionEnd": "15.255.255"
    }
  },

  // 组件框架类型：glass-easel 表示使用新版组件系统
  "componentFramework": "glass-easel",

  // sitemap 配置文件路径（用于搜索引擎收录）
  "sitemapLocation": "sitemap.json",

  // 按需加载策略：requiredComponents 表示只加载必要组件
  "lazyCodeLoading": "requiredComponents"
}

---

三、各配置项详解与可选值说明

1. pages 页面路径列表

• 类型：Array
• 说明：指定小程序的所有页面路径，第一个为启动页。
• 示例：

  "pages": ["pages/index/index"]
  

2. window 窗口配置

配置项	类型	可选值	说明
navigationBarTitleText	String	-	导航栏标题文字内容
navigationBarTextStyle	String	"white" / "black"	导航栏字体颜色
navigationBarBackgroundColor	String	十六进制颜色值	导航栏背景色
backgroundColor	String	十六进制颜色值	页面背景色
backgroundTextStyle	String	"light" / "dark"	下拉 loading 的样式
scrollIndicator	String	"white" / "black" / "none"	页面滚动条样式
navigationStyle	String	"default" / "custom"	是否使用自定义导航栏

注意：若设置 "navigationStyle": "custom"，则原生导航栏不会显示，开发者需自行实现。

3. style

• 类型：String
• 可选值："default" / "v2"
• 说明：启用新版样式系统，推荐使用 "v2"

4. renderer

• 类型：String
• 可选值："webview" / "skyline"
• 说明：
  • "webview"：旧版渲染引擎
  • "skyline"：新一代高性能渲染引擎，支持更多现代 Web 特性

5. rendererOptions

Skyline 子配置项：

配置项	类型	可选值	说明
defaultDisplayBlock	Boolean	true / false	是否将 inline 元素默认转为 block 显示
defaultContentBox	Boolean	true / false	是否启用 content-box 盒模型
tagNameStyleIsolation	String	"legacy" / "strict"	标签名与样式隔离模式
disableABTest	Boolean	true / false	是否禁用 AB 测试
sdkVersionBegin	String	版本号格式如 "3.0.0"	Skyline 生效起始版本
sdkVersionEnd	String	版本号格式如 "15.255.255"	Skyline 生效结束版本

6. componentFramework

• 类型：String
• 可选值："default" / "glass-easel"
• 说明：
  • "default"：旧版组件框架
  • "glass-easel"：新版组件系统，支持更丰富的组件特性

7. sitemapLocation

• 类型：String
• 默认值："sitemap.json"
• 说明：指定 sitemap 文件路径，用于 SEO 搜索引擎收录

8. lazyCodeLoading

• 类型：String
• 可选值："requiredComponents" / "all" / "disabled"
• 说明：
  • "requiredComponents"：按需加载必要组件（推荐）
  • "all"：全部组件都预加载
  • "disabled"：不启用懒加载

---

四、配置项总结表格

配置项	类型	可选值/示例	说明
pages	Array	["pages/index/index"]	页面路径列表（启动页）
window	Object	-	窗口样式配置
style	String	"v2"	启用新版样式系统
renderer	String	"skyline"	使用 Skyline 渲染引擎
rendererOptions.skyline.defaultDisplayBlock	Boolean	true	是否默认 block 显示
rendererOptions.skyline.defaultContentBox	Boolean	true	是否启用 content-box
rendererOptions.skyline.tagNameStyleIsolation	String	"legacy"	标签名样式隔离模式
rendererOptions.skyline.disableABTest	Boolean	true	是否禁用 AB 测试
rendererOptions.skyline.sdkVersionBegin	String	"3.0.0"	Skyline 生效起始版本
rendererOptions.skyline.sdkVersionEnd	String	"15.255.255"	Skyline 生效结束版本
componentFramework	String	"glass-easel"	使用新版组件框架
sitemapLocation	String	"sitemap.json"	sitemap 文件路径
lazyCodeLoading	String	"requiredComponents"	按需加载策略

---

五、补充说明

• 若未显式配置某些字段，微信小程序会使用默认值或继承父级配置。
• 建议在正式发布前关闭 debug 模式，并启用 optimize 和 lazyCodeLoading 提升性能。
• 若使用 Skyline 渲染器，建议熟悉其新特性和兼容性限制。

---

以上是对微信小程序 app.json 文件的完整详解，包含所有配置项说明、示例代码及可选值解释，并附有表格总结，方便查阅和配置管理。