UniApp manifest.json 配置文件完全解析

manifest.json 是 UniApp 项目的核心配置文件，用于指定应用的基本信息、页面路由、界面表现、网络超时时间、窗口表现、导航条、标签栏等。它就像是 UniApp 项目的"身份证"和"功能说明书"，决定了应用如何被打包和运行在各个平台。

一、manifest.json 概述

1.1 文件位置与结构

manifest.json 文件位于项目根目录（HBuilderX 创建的项目）或 src 目录（CLI 创建的项目）。其基本结构如下：

复制代码

{
  "name": "MyUniApp",
  "appid": "__UNI__XXXXXX",
  "description": "项目描述",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": { /* 5+App 特有配置 */ },
  "mp-weixin": { /* 微信小程序特有配置 */ },
  "h5": { /* H5 特有配置 */ },
  "quickapp": { /* 快应用特有配置 */ },
  "mp-alipay": { /* 支付宝小程序特有配置 */ }
}

1.2 配置继承关系

UniApp 的配置采用分层结构：

全局配置：应用基本信息、图标、权限等
平台配置：app-plus（App）、mp-weixin（微信小程序）、h5（H5）等
模块配置：支付、地图、推送等原生模块
优化配置：分包、代码压缩等性能优化

二、基础配置详解

2.1 应用基本信息

配置项	类型	必填	说明
name	String	是	应用名称，显示在桌面图标和启动页
appid	String	是	应用标识，由 DCloud 云端分配
versionName	String	是	版本名称，如"1.0.0"，展示给用户
versionCode	Number	是	版本号，数字越大版本越新
description	String	否	应用描述
locale	String	否	设置当前默认语言

重要提示：uni-app 的 appid 由 DCloud 云端分配，主要用于 DCloud 相关的云服务，请勿自行修改。请注意区分它与微信小程序、iOS 等其它平台分配的 appid。

2.2 图标配置

复制代码

"icons": {
  "android": {
    "36": "static/icons/36x36.png",
    "48": "static/icons/48x48.png",
    "72": "static/icons/72x72.png",
    "96": "static/icons/96x96.png",
    "144": "static/icons/144x144.png",
    "192": "static/icons/192x192.png"
  },
  "ios": {
    "60": "static/icons/60x60.png",
    "120": "static/icons/120x120.png",
    "180": "static/icons/180x180.png"
  }
}

2.3 网络超时配置

复制代码

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

自 HBuilderX 2.5.10 起，默认超时时间由 6 秒改为 60 秒，对齐微信小程序平台。

三、平台特定配置

3.1 App 平台配置（app-plus）

3.1.1 App 启动页配置

复制代码

"app-plus": {
  "splashscreen": {
    "autoclose": true,
    "waiting": true,
    "delay": 3000,
    "alwaysShowBeforeRender": true
  }
}

配置组合说明：

alwaysShowBeforeRender=true + autoclose=true：等待首页渲染完毕自动关闭
alwaysShowBeforeRender=false + autoclose=true：延迟指定时间后自动关闭
alwaysShowBeforeRender=false + autoclose=false：需手动调用 API 关闭

3.1.2 App 模块配置

复制代码

"modules": {
  "Payment": {},
  "Maps": {},
  "Push": {},
  "Share": {}
}

常用模块列表：

Payment：支付
Maps：地图
Push：消息推送
Share：社交分享
Bluetooth：BLE蓝牙
Contacts：系统通讯录
Fingerprint：指纹识别

3.1.3 App 发布配置

复制代码

"distribute": {
  "android": {
    "packagename": "com.example.myapp",
    "permissions": [
      "<uses-permission android:name=\"android.permission.CAMERA\"/>"
    ]
  },
  "ios": {
    "bundleid": "com.example.myapp",
    "privacyDescription": {
      "NSCameraUsageDescription": "需要摄像头进行扫码和拍照"
    }
  }
}

3.2 微信小程序配置（mp-weixin）

复制代码

"mp-weixin": {
  "appid": "wx1234567890abcdef",
  "setting": {
    "urlCheck": false,
    "es6": true,
    "minified": true
  },
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序位置接口的效果展示"
    }
  }
}

3.3 H5 平台配置（h5）

复制代码

"h5": {
  "router": {
    "mode": "hash"
  },
  "devServer": {
    "proxy": {
      "/api": {
        "target": "http://localhost:3000",
        "changeOrigin": true
      }
    }
  },
  "title": "我的H5应用"
}

四、权限配置详解

4.1 App 权限配置

复制代码

"app-plus": {
  "distribute": {
    "android": {
      "permissions": [
        "<uses-permission android:name=\"android.permission.CAMERA\"/>",
        "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>"
      ]
    },
    "ios": {
      "privacyDescription": {
        "NSCameraUsageDescription": "需要摄像头进行扫码和拍照",
        "NSLocationWhenInUseUsageDescription": "需要获取位置信息"
      }
    }
  }
}

4.2 权限申请流程

声明权限：在 manifest.json 中声明需要的权限
运行时请求：在代码中调用相应 API 请求权限
用户授权：系统弹出权限请求对话框
处理结果：根据用户选择执行后续逻辑

五、第三方服务配置

5.1 推送服务配置

复制代码

"sdkConfigs": {
  "push": {
    "unipush": {
      "appid": "your-appid",
      "appkey": "your-appkey",
      "appsecret": "your-appsecret"
    }
  }
}

5.2 支付服务配置

复制代码

"sdkConfigs": {
  "payment": {
    "weixin": {
      "appid": "wx1234567890abcdef",
      "mchid": "your-mchid",
      "key": "your-key"
    },
    "alipay": {
      "appid": "your-alipay-appid"
    }
  }
}

5.3 地图服务配置

复制代码

"sdkConfigs": {
  "maps": {
    "amap": {
      "appkey_ios": "your-ios-key",
      "appkey_android": "your-android-key"
    }
  }
}

六、优化配置

6.1 分包配置

复制代码

"app-plus": {
  "optimization": {
    "subPackages": true
  },
  "runmode": "liberate"
}

注意事项：

分包后需要在 pages.json 中配置具体的分包规则
App 开启分包后，每个分包单独编译成一个 js 文件
首页是 nvue 时，分包不会提升启动速度

6.2 代码压缩配置

复制代码

"app-plus": {
  "optimization": {
    "minify": true,
    "compress": true
  }
}

七、调试与发布配置

7.1 开发环境配置

复制代码

"debug": true,
"networkTimeout": {
  "request": 60000
}

7.2 生产环境配置

复制代码

"debug": false,
"uniStatistics": {
  "enable": true
}

八、配置验证与最佳实践

8.1 配置验证工具

HBuilderX 可视化界面：推荐使用 HBuilderX 提供的可视化界面进行配置，避免 JSON 格式错误
云打包验证：通过云打包验证配置是否正确
真机调试：在真机上调试验证配置效果

8.2 最佳实践建议

权限最小化：只申请应用真正需要的权限，避免过度申请
版本管理：每次发布新版本时，需要更新 versionName 和 versionCode
平台差异化：将平台特有配置写在对应的平台节点下
模块按需配置：不需要的模块可以在打包时剔除，减小应用体积
图标规范：图标文件必须使用 PNG 格式，建议提供多种尺寸

8.3 常见问题与解决方案

8.3.1 配置不生效问题

原因：

配置项位置错误（如将微信小程序配置写在 app-plus 下）
配置项格式错误
需要云打包生效的配置在真机运行时未生效

解决方案：

检查配置项位置是否正确
使用 HBuilderX 可视化界面配置
进行云打包验证

8.3.2 权限申请失败处理

原因：

权限描述不清晰
权限配置错误
用户拒绝授权

解决方案：

提供清晰的权限使用说明
检查权限配置格式
处理权限拒绝的回调逻辑

九、总结

manifest.json 是 UniApp 项目的核心配置文件，掌握其各项配置对于 UniApp 开发至关重要。通过合理配置应用基本信息、平台差异化设置、权限管理以及优化选项，可以确保应用在各平台都能拥有最佳表现。建议使用 HBuilderX 可视化界面进行配置，避免手动编写 JSON 文件时出现格式错误。