完整教程：UniApp manifest.json 配置文件完全解析

文章目录

• • 一、manifest.json 概述
  • • 1.1 什么是 manifest.json
    • 1.2 文件位置与结构
    • 1.3 配置继承关系图
  • 二、基础配置详解
  • • 2.1 应用基本信息
    • 2.2 页面样式与窗口表现
  • 三、平台特定配置
  • • 3.1 App 平台配置（app-plus）
    • • 3.1.1 App 启动页配置
      • 3.1.2 App 模块配置流程图
    • 3.2 微信小程序配置（mp-weixin）
    • • 3.2.1 微信小程序权限配置
    • 3.3 H5 平台配置（h5）
    • • 3.3.1 H5 路由配置详解
  • 四、模块配置详解
  • • 4.1 功能模块配置
    • 4.2 模块使用示例
  • 五、权限配置详解
  • • 5.1 App 权限配置
    • 5.2 权限申请流程图
  • 六、第三方服务配置
  • • 6.1 推送服务配置
    • 6.2 地图服务配置
  • 七、优化配置
  • • 7.1 分包配置
    • 7.2 代码压缩与优化
  • 八、调试与发布配置
  • • 8.1 开发环境配置
    • 8.2 生产环境配置
  • 九、配置验证与最佳实践
  • • 9.1 配置验证工具
    • 9.2 最佳实践建议
    • 9.3 配置管理流程图
  • 十、常见问题与解决方案
  • • 10.1 配置不生效问题
    • 10.2 权限申请失败处理
  • 总结

manifest.json 是 UniApp 项目的核心配置文件，掌握其各项配置对于 UniApp 开发至关重要。本文将深入剖析每个配置项的作用和用法。

一、manifest.json 概述

1.1 什么是 manifest.json

manifest.json 是 UniApp 项目的配置文件，用于指定应用的基本信息、页面路由、界面表现、网络超时时间、窗口表现、导航条、标签栏等。

{
"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 文件位置与结构

project-root/
├── src/
│   ├── pages/
│   ├── static/
│   └── App.vue
├── manifest.json
├── pages.json
└── package.json

1.3 配置继承关系图

二、基础配置详解

2.1 应用基本信息

{
"name": "我的UniApp应用",
"appid": "__UNI__123456",
"description": "这是一个基于UniApp开发的跨平台应用",
"versionName": "1.2.3",
"versionCode": "123",
"transformPx": true,
"lang": "zh-Hans",
"debug": false,
"theme": "light"
}

配置项说明：

配置项	类型	必填	说明
name	String	是	应用名称，显示在桌面图标和启动页
appid	String	是	应用标识，由 DCloud 生成
description	String	否	应用描述
versionName	String	是	版本名称，如 1.0.0
versionCode	String	是	版本号，数字越大版本越新
transformPx	Boolean	否	是否转换 px 为 rpx，默认 true
lang	String	否	应用语言，zh-Hans、en 等
debug	Boolean	否	是否开启调试模式
theme	String	否	主题模式，light/dark/auto

2.2 页面样式与窗口表现

{
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "我的应用",
"navigationBarBackgroundColor": "#FFFFFF",
"backgroundColor": "#F8F8F8",
"backgroundTextStyle": "dark",
"enablePullDownRefresh": false,
"onReachBottomDistance": 50,
"pageOrientation": "portrait",
"rpxCalcMaxDeviceWidth": 1242,
"rpxCalcBaseDeviceWidth": 375,
"usingComponents": {}
}
}

globalStyle 配置说明：

// 在页面中可通过 getApp().globalStyle 访问
const app = getApp();
console.log(app.globalStyle.navigationBarBackgroundColor);

三、平台特定配置

3.1 App 平台配置（app-plus）

{
"app-plus": {
"usingComponents": true,
"nvueStyleCompiler": "uni-app",
"compilerVersion": 3,
"splashscreen": {
"autoclose": true,
"waiting": true,
"delay": 0
},
"modules": {
"VideoPlayer": {},
"Maps": {},
"Payment": {}
},
"distribute": {
"android": {
"packagename": "com.example.myapp",
"versionCode": "100",
"permissions": [
"<uses-permission android:name=\"android.permission.CAMERA\"/>"
]
},
"ios": {
"bundleid": "com.example.myapp",
"versioncode": "100",
"urlschemes": ["myapp"],
"privacyDescription": {
"NSPhotoLibraryUsageDescription": "需要访问相册上传图片",
"NSCameraUsageDescription": "需要摄像头进行扫码和拍照"
}
}
},
"plugins": {
"oauth": {
"weixin": {
"appid": "wx1234567890",
"appsecret": "wx_app_secret_here"
},
"qq": {
"appid": "qq1234567890"
}
}
}
}
}

3.1.1 App 启动页配置

"splashscreen": {
"autoclose": true,
"waiting": true,
"delay": 3000,
"target": "id:1",
"alwaysShowBeforeRender": false,
"backgroundColor": "#FFFFFF"
}

3.1.2 App 模块配置流程图

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

{
"mp-weixin": {
"appid": "wx1234567890abcdef",
"setting": {
"urlCheck": false,
"es6": true,
"enhance": true,
"postcss": true,
"minified": true,
"newFeature": true
},
"usingComponents": true,
"permission": {
"scope.userLocation": {
"desc": "你的位置信息将用于小程序位置接口的效果展示"
}
},
"requiredBackgroundModes": ["location"],
"plugins": {
"myPlugin": {
"version": "1.0.0",
"provider": "wxid1234567890"
}
},
"navigateToMiniProgramAppIdList": [
"wx1234567890abcdef"
],
"workers": "workers",
"optimization": {
"subPackages": true
},
"lazyCodeLoading": "requiredComponents",
"entranceDeclare": {
"locationMessage": {
"path": "pages/index/index",
"query": "foo=bar"
}
}
}
}

3.2.1 微信小程序权限配置

"permission": {
"scope.userLocation": {
"desc": "需要获取您的位置信息，用于提供附近服务"
},
"scope.record": {
"desc": "需要访问您的麦克风，用于语音输入"
},
"scope.writePhotosAlbum": {
"desc": "需要保存图片到您的相册"
}
}

3.3 H5 平台配置（h5）

{
"h5": {
"devServer": {
"https": false,
"port": 8080,
"disableHostCheck": true,
"proxy": {
"/api": {
"target": "https://api.example.com",
"changeOrigin": true,
"secure": false
}
}
},
"publicPath": "/",
"router": {
"mode": "hash",
"base": "/"
},
"template": "index.html",
"title": "我的H5应用",
"meta": {
"viewport": "width=device-width, initial-scale=1.0, user-scalable=no",
"description": "基于UniApp开发的H5应用",
"keywords": "UniApp,H5,跨平台"
},
"optimization": {
"treeShaking": {
"enable": true
}
},
"sdkConfigs": {
"maps": {
"amap": {
"key": "your-amap-key"
}
}
}
}
}

3.3.1 H5 路由配置详解

"router": {
"mode": "history",
"base": "/myapp/",
"linkActiveClass": "router-link-active",
"linkExactActiveClass": "router-link-exact-active"
}

路由模式对比：

模式	优点	缺点	适用场景
hash	兼容性好，部署简单	URL 不美观	传统 H5 项目
history	URL 美观，SEO友好	需要服务端支持	企业官网、需要SEO的项目

四、模块配置详解

4.1 功能模块配置

{
"modules": {
"Geolocation": {
"version": "1.0.0",
"provider": "uni-geolocation"
},
"Maps": {
"version": "1.0.0",
"provider": "uni-maps"
},
"Payment": {
"version": "1.0.0",
"provider": "uni-payment"
},
"Push": {
"version": "1.0.0",
"provider": "uni-push"
},
"Share": {
"version": "1.0.0",
"provider": "uni-share"
},
"OAuth": {
"version": "1.0.0",
"provider": "uni-oauth"
}
}
}

4.2 模块使用示例

// 在页面中使用配置的模块
export default {
methods: {
async getLocation() {
try {
const res = await uni.getLocation({
type: 'wgs84'
});
console.log('当前位置:', res);
} catch (error) {
console.error('获取位置失败:', error);
}
},
async makePayment() {
try {
const res = await uni.requestPayment({
provider: 'wxpay',
orderInfo: 'order_info_here'
});
console.log('支付成功:', res);
} catch (error) {
console.error('支付失败:', error);
}
}
}
}

五、权限配置详解

5.1 App 权限配置

{
"app-plus": {
"distribute": {
"android": {
"permissions": [
"<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
"<uses-permission android:name=\"android.permission.CAMERA\"/>",
"<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>",
"<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>",
"<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>"
],
"customPermissions": false
},
"ios": {
"privacyDescription": {
"NSLocationWhenInUseUsageDescription": "应用需要您的位置信息来提供附近服务",
"NSCameraUsageDescription": "应用需要访问摄像头进行扫码和拍照",
"NSPhotoLibraryUsageDescription": "应用需要访问相册来选择图片",
"NSMicrophoneUsageDescription": "应用需要访问麦克风进行语音输入",
"NSContactsUsageDescription": "应用需要访问通讯录来添加好友"
}
}
}
}
}

5.2 权限申请流程图

六、第三方服务配置

6.1 推送服务配置

{
"app-plus": {
"plugins": {
"push": {
"unipush": {
"appid": "your-unipush-appid",
"appkey": "your-unipush-appkey",
"appsecret": "your-unipush-appsecret"
},
"igexin": {
"appid": "your-getui-appid",
"appkey": "your-getui-appkey",
"appsecret": "your-getui-appsecret"
}
}
}
}
}

6.2 地图服务配置

{
"app-plus": {
"maps": {
"amap": {
"key": "your-amap-key-here",
"securityCode": "your-security-code"
},
"google": {
"key": "your-google-map-key"
}
}
},
"mp-weixin": {
"requiredPrivateInfos": ["getLocation"],
"permission": {
"scope.userLocation": {
"desc": "需要获取您的位置信息用于地图展示"
}
}
}
}

七、优化配置

7.1 分包配置

{
"app-plus": {
"optimization": {
"subPackages": true
}
},
"mp-weixin": {
"optimization": {
"subPackages": true
}
}
}

7.2 代码压缩与优化

{
"app-plus": {
"optimization": {
"treeShaking": {
"enable": true
}
}
},
"h5": {
"optimization": {
"treeShaking": {
"enable": true
},
"splitChunks": {
"enable": true,
"chunks": "all"
}
}
}
}

八、调试与发布配置

8.1 开发环境配置

{
"name": "MyApp-Dev",
"versionName": "1.0.0-dev",
"debug": true,
"app-plus": {
"distribute": {
"sdkConfigs": {
"oauth": {
"weixin": {
"appid": "wx_dev_appid",
"appsecret": "wx_dev_appsecret"
}
}
}
}
},
"h5": {
"devServer": {
"port": 3000,
"proxy": {
"/api": {
"target": "https://dev-api.example.com",
"changeOrigin": true
}
}
}
}
}

8.2 生产环境配置

{
"name": "我的应用",
"versionName": "1.0.0",
"debug": false,
"app-plus": {
"distribute": {
"sdkConfigs": {
"oauth": {
"weixin": {
"appid": "wx_prod_appid",
"appsecret": "wx_prod_appsecret"
}
}
}
}
},
"h5": {
"publicPath": "https://cdn.example.com/myapp/",
"router": {
"mode": "history",
"base": "/"
}
}
}

九、配置验证与最佳实践

9.1 配置验证工具

// utils/validateManifest.js
class ManifestValidator {
static validate(manifest) {
const errors = [];
// 检查必填字段
if (!manifest.name) errors.push('应用名称(name)为必填项');
if (!manifest.appid) errors.push('应用标识(appid)为必填项');
if (!manifest.versionName) errors.push('版本名称(versionName)为必填项');
if (!manifest.versionCode) errors.push('版本号(versionCode)为必填项');
// 检查平台特定配置
if (manifest['app-plus']) {
const appPlus = manifest['app-plus'];
if (appPlus.distribute) {
if (appPlus.distribute.android && !appPlus.distribute.android.packagename) {
errors.push('Android包名(packagename)为必填项');
}
if (appPlus.distribute.ios && !appPlus.distribute.ios.bundleid) {
errors.push('iOS Bundle ID(bundleid)为必填项');
}
}
}
return errors;
}
static generateTemplate() {
return {
"name": "",
"appid": "",
"description": "",
"versionName": "1.0.0",
"versionCode": "100",
"transformPx": false,
"app-plus": {
"distribute": {
"android": {
"packagename": "com.example.myapp"
},
"ios": {
"bundleid": "com.example.myapp"
}
}
}
};
}
}

9.2 最佳实践建议

1. 环境分离：为开发、测试、生产环境配置不同的 manifest
2. 权限最小化：只申请必要的权限
3. 版本管理：规范版本号命名
4. 安全配置：敏感信息不要硬编码在配置中
5. 定期检查：定期更新平台特定配置

9.3 配置管理流程图

十、常见问题与解决方案

10.1 配置不生效问题

// 检查配置是否生效
uni.getSystemInfo({
success: (res) => {
console.log('平台信息:', res.platform);
console.log('应用信息:', res.appName);
}
});

10.2 权限申请失败处理

// 权限申请封装
class PermissionManager {
static async requestPermission(permission) {
return new Promise((resolve, reject) => {
uni.authorize({
scope: permission,
success: resolve,
fail: (error) => {
// 引导用户手动开启
this.showPermissionGuide(permission, reject);
}
});
});
}
static showPermissionGuide(permission, reject) {
uni.showModal({
title: '权限申请',
content: '需要您授权相关权限才能使用该功能',
success: (res) => {
if (res.confirm) {
uni.openSetting({
success: (settingRes) => {
if (settingRes.authSetting[permission]) {
resolve();
} else {
reject(new Error('用户拒绝授权'));
}
}
});
} else {
reject(new Error('用户取消授权'));
}
}
});
}
}

总结

manifest.json 是 UniApp 项目的核心配置文件，掌握其各项配置对于开发高质量的跨平台应用至关重要。本文详细介绍了：

1. 基础配置：应用基本信息、全局样式等
2. 平台配置：App、小程序、H5 等平台的特定配置
3. 模块配置：功能模块的声明和配置
4. 权限配置：各平台权限申请配置
5. 优化配置：性能优化相关配置
6. 最佳实践：配置管理和验证

通过合理配置 manifest.json，可以充分发挥 UniApp 的跨平台能力，提升应用质量和用户体验。

---

本文标签： #UniApp #manifest.json #跨端开发 #移动开发 #前端开发

版权声明： 本文由CSDN博主原创，转载请注明出处。欢迎技术交流与讨论！