# 全局配置

小程序根目錄下的 app.json 文件用來對(duì)微信小程序進(jìn)行全局配置。文件內(nèi)容為一個(gè) JSON 對(duì)象，有以下屬性：

# 配置項(xiàng)

# entryPagePath

指定小程序的默認(rèn)啟動(dòng)路徑（首頁），常見情景是從微信聊天列表頁下拉啟動(dòng)、小程序列表啟動(dòng)等。如果不填，將默認(rèn)為 pages 列表的第一項(xiàng)。不支持帶頁面路徑參數(shù)。

{
  "entryPagePath": "pages/index/index"
}

# pages

用于指定小程序由哪些頁面組成，每一項(xiàng)都對(duì)應(yīng)一個(gè)頁面的 路徑（含文件名） 信息。文件名不需要寫文件后綴，框架會(huì)自動(dòng)去尋找對(duì)應(yīng)位置的 .json, .js, .wxml, .wxss 四個(gè)文件進(jìn)行處理。

未指定 entryPagePath 時(shí)，數(shù)組的第一項(xiàng)代表小程序的初始頁面（首頁）。

小程序中新增/減少頁面，都需要對(duì) pages 數(shù)組進(jìn)行修改。

如開發(fā)目錄為：

├── app.js
├── app.json
├── app.wxss
├── pages
│?? │── index
│?? │   ├── index.wxml
│?? │   ├── index.js
│?? │   ├── index.json
│?? │   └── index.wxss
│?? └── logs
│??     ├── logs.wxml
│??     └── logs.js
└── utils

則需要在 app.json 中寫

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

# window

用于設(shè)置小程序的狀態(tài)欄、導(dǎo)航條、標(biāo)題、窗口背景色。

• 注 1：HexColor（十六進(jìn)制顏色值），如"#ff00ff"
• 注 2：關(guān)于navigationStyle
  • iOS/Android 客戶端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。
  • iOS/Android 客戶端 6.7.2 版本開始，navigationStyle: custom 對(duì) web-view 組件無效
  • 開啟 custom 后，低版本客戶端需要做好兼容。開發(fā)者工具基礎(chǔ)庫版本切到 1.7.0（不代表最低版本，只供調(diào)試用）可方便切到舊視覺

# restartStrategy

基礎(chǔ)庫 2.8.0 開始支持，低版本需做兼容處理。

重新啟動(dòng)策略配置

如：

{
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "微信接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
  }
}

# tabBar

如果小程序是一個(gè)多 tab 應(yīng)用（客戶端窗口的底部或頂部有 tab 欄可以切換頁面），可以通過 tabBar 配置項(xiàng)指定 tab 欄的表現(xiàn)，以及 tab 切換時(shí)顯示的對(duì)應(yīng)頁面。

其中 list 接受一個(gè)數(shù)組，只能配置最少 2 個(gè)、最多 5 個(gè) tab。tab 按數(shù)組的順序排序，每個(gè)項(xiàng)都是一個(gè)對(duì)象，其屬性值如下：

# networkTimeout

各類網(wǎng)絡(luò)請(qǐng)求的超時(shí)時(shí)間，單位均為毫秒。

# debug

可以在開發(fā)者工具中開啟 debug 模式，在開發(fā)者工具的控制臺(tái)面板，調(diào)試信息以 info 的形式給出，其信息有 Page 的注冊(cè)，頁面路由，數(shù)據(jù)更新，事件觸發(fā)等?？梢詭椭_發(fā)者快速定位一些常見的問題。

# functionalPages

基礎(chǔ)庫 2.1.0 開始支持，低版本需做兼容處理。

插件所有者小程序需要設(shè)置這一項(xiàng)來啟用插件功能頁。

# subpackages

微信客戶端 6.6.0 ，基礎(chǔ)庫 1.7.3 及以上版本支持

啟用分包加載時(shí)，聲明項(xiàng)目分包結(jié)構(gòu)。

寫成 subPackages 也支持。

# workers

基礎(chǔ)庫 1.9.90 開始支持，低版本需做兼容處理。

使用 Worker 處理多線程任務(wù)時(shí)，設(shè)置 Worker 代碼放置的目錄

# requiredBackgroundModes

微信客戶端 6.7.2 及以上版本支持

申明需要后臺(tái)運(yùn)行的能力，類型為數(shù)組。目前支持以下項(xiàng)目：

• audio: 后臺(tái)音樂播放
• location: 后臺(tái)定位

如：

{
  "pages": ["pages/index/index"],
  "requiredBackgroundModes": ["audio", "location"]
}

注：在此處申明了后臺(tái)運(yùn)行的接口，開發(fā)版和體驗(yàn)版上可以直接生效，正式版還需通過審核。

# requiredPrivateInfos

自 2022 年 7 月 14 日后發(fā)布的小程序，使用以下8個(gè)地理位置相關(guān)接口時(shí)，需要聲明該字段，否則將無法正常使用。2022 年 7 月 14 日前發(fā)布的小程序不受影響。

申明需要使用的地理位置相關(guān)接口，類型為數(shù)組。目前支持以下項(xiàng)目：

• getFuzzyLocation: 獲取模糊地理位置
• getLocation: 獲取精確地理位置
• onLocationChange: 監(jiān)聽實(shí)時(shí)地理位置變化事件
• startLocationUpdate: 接收位置消息（前臺(tái)）
• startLocationUpdateBackground: 接收位置消息（前后臺(tái)）
• chooseLocation: 打開地圖選擇位置
• choosePoi: 打開POI列表選擇位置
• chooseAddress: 獲取用戶地址信息

如：

{
  "pages": ["pages/index/index"],
  "requiredPrivateInfos": [ 
    "getLocation",
    "onLocationChange",
    "startLocationUpdateBackground",
    "chooseAddress"
  ]
}

注：若使用以上接口，均需在小程序管理后臺(tái)，「開發(fā)」-「開發(fā)管理」-「接口設(shè)置」中自助開通該接口權(quán)限。

# plugins

基礎(chǔ)庫 1.9.6 開始支持，低版本需做兼容處理。

聲明小程序需要使用的插件。

# preloadRule

基礎(chǔ)庫 2.3.0 開始支持，低版本需做兼容處理。

聲明分包預(yù)下載的規(guī)則。

# resizable

基礎(chǔ)庫 2.3.0 開始支持，低版本需做兼容處理。

在 iPad 上運(yùn)行的小程序可以設(shè)置支持屏幕旋轉(zhuǎn)。

在 PC 上運(yùn)行的小程序，用戶可以按照任意比例拖動(dòng)窗口大小，也可以在小程序菜單中最大化窗口

# usingComponents

開發(fā)者工具 1.02.1810190 及以上版本支持

在 app.json 中聲明的自定義組件視為全局自定義組件，在小程序內(nèi)的頁面或自定義組件中可以直接使用而無需再聲明。建議僅在此聲明幾乎所有頁面都會(huì)用到的自定義組件。

注1：全局自定義組件會(huì)視為被所有頁面依賴，會(huì)在所有頁面啟動(dòng)時(shí)進(jìn)行初始化，影響啟動(dòng)性能且會(huì)占用主包大小。只被個(gè)別頁面或分包引用的自定義組件應(yīng)盡量在頁面配置中聲明。 注2：在全局聲明使用率低的自定義組件會(huì)大幅影響按需注入的效果。

# permission

微信客戶端 7.0.0 及以上版本支持

小程序接口權(quán)限相關(guān)設(shè)置。字段類型為 Object，結(jié)構(gòu)為：

PermissionObject 結(jié)構(gòu)

如：

{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息將用于小程序位置接口的效果展示" // 高速公路行駛持續(xù)后臺(tái)定位
    }
  }
}

# sitemapLocation

指明 sitemap.json 的位置；默認(rèn)為 'sitemap.json' 即在 app.json 同級(jí)目錄下名字的 sitemap.json 文件

# style

基礎(chǔ)庫 2.8.0 開始支持，低版本需做兼容處理。

微信客戶端 7.0 開始，UI 界面進(jìn)行了大改版。小程序也進(jìn)行了基礎(chǔ)組件的樣式升級(jí)。app.json 中配置 "style": "v2"可表明啟用新版的組件樣式。

本次改動(dòng)涉及的組件有 button icon radio checkbox switch slider?？汕巴〕绦蚴纠M(jìn)行體驗(yàn)。

# useExtendedLib

基礎(chǔ)庫 2.2.1 開始支持，低版本需做兼容處理。

最新的 nightly 版開發(fā)者工具開始支持，同時(shí)基礎(chǔ)庫從支持 npm 的版本（2.2.1）起支持

指定需要引用的擴(kuò)展庫。目前支持以下項(xiàng)目：

• kbone: 多端開發(fā)框架
• weui: WeUI 組件庫

指定后，相當(dāng)于引入了對(duì)應(yīng)擴(kuò)展庫相關(guān)的最新版本的 npm 包，同時(shí)也不占用小程序的包體積。rc工具版本支持分包引用。用法如下：

{
  "useExtendedLib": {
    "kbone": true,
    "weui": true
  }
}

# entranceDeclare

微信客戶端 7.0.9 及以上版本支持，iOS 暫不支持

聊天位置消息用打車類小程序打開，詳情參考。

"entranceDeclare": {
    "locationMessage": {
        "path": "pages/index/index",
        "query": "foo=bar"
    }
}

# darkmode

開發(fā)者工具 1.03.2004271 及以上版本支持，基礎(chǔ)庫 2.11.0 及以上版本支持

微信iOS客戶端 7.0.12 版本、Android客戶端 7.0.13 版本正式支持 DarkMode，可通過配置"darkmode": true表示當(dāng)前小程序可適配 DarkMode，所有基礎(chǔ)組件均會(huì)根據(jù)系統(tǒng)主題展示不同的默認(rèn)樣式，navigation bar 和 tab bar 也會(huì)根據(jù)開發(fā)者的配置自動(dòng)切換。

配置后，請(qǐng)根據(jù)DarkMode 適配指南自行完成基礎(chǔ)樣式以外的適配工作。

{
  "darkmode": true
}

# themeLocation

自定義 theme.json 的路徑，當(dāng)配置"darkmode":true時(shí)，當(dāng)前配置文件為必填項(xiàng)。

{
  "themeLocation": "/path/to/theme.json"
}

# lazyCodeLoading

目前僅支持值 requiredComponents，代表開啟小程序「按需注入」特性。

{
  "lazyCodeLoading": "requiredComponents"
}

# singlePage

基礎(chǔ)庫 2.11.3 及以上版本支持，目前分享到朋友圈 (Beta) 后打開會(huì)進(jìn)入單頁模式

單頁模式相關(guān)配置

# embeddedAppIdList

指定小程序可通過wx.openEmbeddedMiniProgram打開的小程序名單。

{
  "embeddedAppIdList": ["wxe5f52902cf4de896"]
}

# halfPage

{
  "halfPage": {
    "firstPageNavigationStyle": "custom"
  }
}

# debugOptions

小程序調(diào)試相關(guān)配置項(xiàng)

{
  "debugOptions": {
    "enableFPSPanel": "false"
  }
}

# enablePassiveEvent

touch 相關(guān)事件默認(rèn)的 passive 為 false。如果小程序不使用 catchtouch* 事件時(shí)，可以通過這個(gè)選項(xiàng)將 passive 置為 true，以提高滾動(dòng)性能。具體原理可參考MDN。

可以直接設(shè)置這個(gè)選項(xiàng)為 true，也可以分別控制某個(gè)事件。

{
  "enablePassiveEvent": true
}

{
  "enablePassiveEvent": {
    "touchstart": true
  }
}

注意

開啟了 enablePassiveEvent 之后，使用以下內(nèi)置組件可能會(huì)導(dǎo)致出現(xiàn)非預(yù)期的行為，但不會(huì)導(dǎo)致頁面白屏。

touchmove 設(shè)置為 true，如下內(nèi)置組件可能會(huì)出現(xiàn)非預(yù)期表現(xiàn)：

• movable-area
• movable-view
• video
• canvas（windows、mac 小程序）
• picker-view-column

wheel 設(shè)置為 true，如下內(nèi)置組件可能會(huì)出現(xiàn)非預(yù)期表現(xiàn)：

• swiper（mac 小程序）
• map

推薦在用到如上組件的頁面中將對(duì)應(yīng)事件的 enablePassiveEvent 設(shè)置為 false 以避免非預(yù)期行為。

自 2.25.1 之后，在頁面/組件實(shí)例中新增 getPassiveEvent / setPassiveEvent 兩個(gè)接口，用于在運(yùn)行時(shí)獲取/切換頁面或組件所在頁面的 passive 配置。

Component({
    methods: {
        getPassive() {
            this.getPassiveEvent((passive) => {
                const { touchstart, touchmove, wheel } = passive
            })
        },
        setPassive() {
            const passive {
                touchstart: false,
                touchmove: true,
                wheel: false,
            }
            this.setPassiveEvent(passive)
        }
    }
})

# resolveAlias

使用 resolveAlias 配置項(xiàng)用來自定義模塊路徑的映射規(guī)則。

配置了之后，會(huì)對(duì) require 里的模塊路徑進(jìn)行規(guī)則匹配并映射成配置的路徑。

如果命中多條映射規(guī)則，則取最長(zhǎng)的命中規(guī)則。

{
  "resolveAlias": {
    "~/*": "/*",
    "~/origin/*": "origin/*",
    "@utils/*": "utils/*",
    "subBUtils/*": "subpackageB/utils/*"
  }
}

注意

1. resolveAlias 進(jìn)行的是路徑匹配，其中的 key 和 value 須以 /* 結(jié)尾。

配置了上述路徑映射規(guī)則，會(huì)做如下匹配并轉(zhuǎn)換

• ~/mod.js -> mod.js
• ~/origin/mod.js -> origin/mod.js
• @utils/mod.js -> utils/mod.js
• subBUtils/mod.js -> subpackageB/utils/mod.js

2. 如果在 project.config.json 中指定了 miniprogramRoot，則 /* 指代的根目錄是 miniprogramRoot 對(duì)應(yīng)的路徑，而不是開發(fā)者工具項(xiàng)目的根目錄

# renderer

指定小程序全局的默認(rèn)渲染后端。

可選值：webview, skyline

默認(rèn)值：webview

# rendererOptions

小程序渲染后端的相關(guān)配置選項(xiàng)

# SkylineOptions

Skyline 渲染引擎的相關(guān)配置項(xiàng)

{
  "rendererOptions": {
    "skyline": {
      "disableABTest": true,
      "defaultDisplayBlock": true,
      "defaultContentBox": true,
      "tagNameStyleIsolation": "legacy",
      "enableScrollViewAutoSize": true,
    }
  }
}

# componentFramework

指定小程序使用的組件框架

可選值：exparser, glass-easel

默認(rèn)值：exparser

# chatTools

指定聊天工具對(duì)應(yīng)的獨(dú)立分包

{
  "chatTools": [
    {
      "root": "packageChatTool",
      "entryPagePath": "pages/activity_create/index",
      "desc": "群簽到工具",
      "scopes": [
        "scope.userLocation"
      ]
    }
  ]
}

# 配置示例

{
  "pages": ["pages/index/index", "pages/logs/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首頁"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志"
      }
    ]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "debug": true,
}