项目配置

项目配置是将您的 uniapp 项目与开发工具关联，并设置打包参数的过程。

概述

项目配置包括：

导入 uniapp 项目
配置应用信息
设置打包参数
配置图标和启动页
设置权限和功能模块

导入项目

1. 打开项目

在 uniapp 开发工具中：

点击"文件" > "打开项目"
或点击欢迎页面的"导入项目"按钮
选择您的 uniapp 项目根目录

2. 项目识别

工具会自动识别项目类型：

HBuilderX 项目: 包含 manifest.json 文件
CLI 项目: 包含 package.json 和 vue.config.js

提示

确保项目已在 HBuilderX 或 CLI 中创建并完成基本开发。

3. 验证项目结构

工具会检查项目是否包含必需文件：

your-project/
├── manifest.json         # 应用配置文件（必需）
├── pages.json           # 页面路由配置（必需）
├── App.vue              # 应用入口（必需）
├── main.js              # 入口文件
├── uni.scss             # 全局样式变量
├── package.json         # 依赖配置
└── pages/              # 页面目录
    └── index/
        └── index.vue

应用基本信息配置

1. 应用信息

在"项目配置" > "应用信息"中设置：

基本信息：

应用名称: 显示在设备上的应用名称
应用描述: 应用的简短描述
版本名称: 用户可见的版本号，如 1.0.0
版本号: 内部版本号，必须为整数，如 100

应用标识：

AppID: uniapp 应用的唯一标识符
Bundle ID (iOS): iOS 应用包名，格式：com.company.appname
Package Name (Android): Android 应用包名，格式：com.company.appname

注意

Bundle ID 和 Package Name 一旦发布后不应更改
必须使用您拥有的域名反向格式
只能包含字母、数字和点号

2. 示例配置

json

{
  "name": "我的应用",
  "description": "一个优秀的 uniapp 应用",
  "versionName": "1.0.0",
  "versionCode": 100,
  "appid": "__UNI__1234567",
  "ios": {
    "bundleId": "com.mycompany.myapp"
  },
  "android": {
    "packageName": "com.mycompany.myapp"
  }
}

Android 平台配置

1. 基本设置

最低 SDK 版本：

推荐：API 21 (Android 5.0) 或更高
设置过低可能导致某些功能不可用
设置过高会减少兼容设备数量

目标 SDK 版本：

推荐：API 33 (Android 13) 或最新稳定版
影响应用在新系统上的行为

构建工具版本：

推荐：33.0.0 或更高
需要与 Android SDK 中已安装的版本匹配

2. 签名配置

Android 应用发布需要签名。

创建密钥库

使用 keytool 创建密钥：

bash

keytool -genkey -v -keystore my-release-key.keystore \
  -alias my-key-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

参数说明：

keystore: 密钥库文件名
alias: 密钥别名
keyalg: 加密算法
keysize: 密钥长度
validity: 有效期（天）

配置签名

在工具中配置签名信息：

密钥库路径: 选择 .keystore 文件
密钥库密码: 创建时设置的密码
密钥别名: 创建时设置的别名
密钥密码: 密钥的密码

重要

妥善保管密钥库文件和密码
密钥库丢失将无法更新应用
建议使用密码管理工具保存密码

3. 权限配置

选择应用需要的权限：

常用权限：

📷 相机 (CAMERA)
📸 读取相册 (READ_EXTERNAL_STORAGE)
💾 写入存储 (WRITE_EXTERNAL_STORAGE)
📍 位置信息 (ACCESS_FINE_LOCATION)
📞 拨打电话 (CALL_PHONE)
📱 读取电话状态 (READ_PHONE_STATE)
🔔 通知 (POST_NOTIFICATIONS)

提示

只请求应用实际需要的权限，过多权限可能导致用户不信任。

4. 功能模块

选择要包含的 uniapp 功能模块：

地图: 高德地图、百度地图、腾讯地图
支付: 支付宝、微信支付
分享: 微信分享、QQ 分享、新浪微博
推送: uni-push、个推、极光推送
统计: 友盟统计、Google Analytics
登录: 微信登录、QQ 登录、Apple 登录

每个模块可能需要额外配置，如 API Key。

iOS 平台配置

1. 基本设置

部署目标：

推荐：iOS 11.0 或更高
设置过低可能无法使用新 API
设置过高会减少兼容设备

设备类型：

iPhone
iPad
Universal (通用应用)

2. 证书和描述文件

开发证书

用于开发和测试：

在 Apple Developer 后台创建开发证书
下载 .cer 文件并双击安装
在工具中选择对应的证书

发布证书

用于发布到 App Store 或企业分发：

创建发布证书
安装到钥匙串
在工具中选择

描述文件

开发描述文件: 用于真机调试
Ad Hoc 描述文件: 用于内测分发
App Store 描述文件: 用于 App Store 发布

在工具中：

自动检测已安装的描述文件
或手动导入 .mobileprovision 文件

3. 权限配置

iOS 需要在 Info.plist 中声明权限使用说明：

xml

<key>NSCameraUsageDescription</key>
<string>需要使用相机拍摄照片</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册选择图片</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>需要获取您的位置信息</string>

在工具中，为每个权限添加使用说明（中英文）。

4. Capabilities

配置应用能力：

推送通知 (Push Notifications)
应用内购买 (In-App Purchase)
Apple 登录 (Sign In with Apple)
关联域名 (Associated Domains)
后台模式 (Background Modes)

图标和启动页

1. 应用图标

Android 图标尺寸：

密度	尺寸	说明
mdpi	48x48	低密度屏幕
hdpi	72x72	中密度屏幕
xhdpi	96x96	高密度屏幕
xxhdpi	144x144	超高密度屏幕
xxxhdpi	192x192	超超高密度屏幕

iOS 图标尺寸：

设备	尺寸	说明
iPhone	120x120	@2x
iPhone	180x180	@3x
iPad	152x152	@2x
App Store	1024x1024	商店图标

快速生成图标

工具提供图标生成功能：

准备一张 1024x1024 的高清图标
点击"生成图标"
自动生成各尺寸图标

2. 启动页

Android 启动页：

默认启动图：1080x1920 (竖屏)
横屏启动图：1920x1080 (可选)
支持 9-patch 格式

iOS 启动页：

使用 LaunchScreen.storyboard
或提供各尺寸启动图

推荐使用 storyboard，适配所有屏幕尺寸。

高级配置

1. 自定义资源

Android：

添加原生资源文件到 nativeResources/android/
自动合并到打包产物

iOS：

添加资源到 nativeResources/ios/
自动包含在 Xcode 项目中

2. 自定义配置文件

Android Gradle 配置：

编辑 android.gradle 自定义构建参数：

gradle

android {
    defaultConfig {
        // 自定义配置
        manifestPlaceholders = [
            APP_NAME: "我的应用"
        ]
    }
}

iOS Info.plist：

添加自定义键值对。

3. 离线资源

配置是否使用离线资源：

在线资源: 从服务器加载
离线资源: 打包到应用中

配置文件示例

完整的 manifest.json 配置示例：

json

{
  "name": "示例应用",
  "appid": "__UNI__1234567",
  "description": "这是一个示例应用",
  "versionName": "1.0.0",
  "versionCode": "100",

  "app-plus": {
    "modules": {
      "Maps": {},
      "Payment": {},
      "Share": {},
      "Push": {}
    },

    "distribute": {
      "android": {
        "packagename": "com.example.app",
        "minSdkVersion": 21,
        "targetSdkVersion": 33,
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>",
          "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>"
        ]
      },

      "ios": {
        "bundleId": "com.example.app",
        "deploymentTarget": "11.0",
        "privacyDescription": {
          "NSCameraUsageDescription": "需要使用相机",
          "NSPhotoLibraryUsageDescription": "需要访问相册"
        }
      },

      "icons": {
        "android": {
          "hdpi": "res/icons/72x72.png",
          "xhdpi": "res/icons/96x96.png",
          "xxhdpi": "res/icons/144x144.png",
          "xxxhdpi": "res/icons/192x192.png"
        },
        "ios": {
          "iphone": {
            "app@2x": "res/icons/120x120.png",
            "app@3x": "res/icons/180x180.png"
          },
          "ipad": {
            "app@2x": "res/icons/152x152.png"
          }
        }
      }
    }
  }
}

常见问题

包名冲突

问题: 提示包名已被使用

解决方案:

更改为唯一的包名
使用您自己的域名反向格式

签名验证失败

问题: Android 签名配置错误

解决方案:

检查密钥库路径是否正确
确认密码输入正确
验证密钥别名

iOS 证书不匹配

问题: 证书和描述文件不匹配

解决方案:

确认证书类型（开发/发布）
检查 Bundle ID 是否一致
重新下载描述文件

图标显示异常

问题: 图标在设备上显示模糊或变形

解决方案:

确保图标尺寸正确
使用高质量 PNG 图片
避免透明度过高

配置检查清单

在开始打包前，确认：

[ ] 应用基本信息已填写
[ ] Bundle ID / Package Name 已设置
[ ] 版本号符合规范
[ ] Android 签名已配置（发布时）
[ ] iOS 证书和描述文件已配置
[ ] 权限配置完整且必要
[ ] 图标和启动页已设置
[ ] 功能模块已选择并配置

下一步

项目配置完成后，您可以：

配置离线 AppKey以支持离线打包
开始本地打包
了解 VIP 功能获取更多高级能力

项目配置 ​

概述 ​

导入项目 ​

1. 打开项目 ​

2. 项目识别 ​

3. 验证项目结构 ​

应用基本信息配置 ​

1. 应用信息 ​

2. 示例配置 ​

Android 平台配置 ​

1. 基本设置 ​

2. 签名配置 ​

创建密钥库 ​

配置签名 ​

3. 权限配置 ​

4. 功能模块 ​

iOS 平台配置 ​

1. 基本设置 ​

2. 证书和描述文件 ​

开发证书 ​

发布证书 ​

描述文件 ​

3. 权限配置 ​

4. Capabilities ​

图标和启动页 ​

1. 应用图标 ​

快速生成图标 ​

2. 启动页 ​

高级配置 ​

1. 自定义资源 ​

2. 自定义配置文件 ​

3. 离线资源 ​

配置文件示例 ​

常见问题 ​

包名冲突 ​

签名验证失败 ​

iOS 证书不匹配 ​

图标显示异常 ​

配置检查清单 ​

下一步 ​

项目配置

概述

导入项目

1. 打开项目

2. 项目识别

3. 验证项目结构

应用基本信息配置

1. 应用信息

2. 示例配置

Android 平台配置

1. 基本设置

2. 签名配置

创建密钥库

配置签名

3. 权限配置

4. 功能模块

iOS 平台配置

1. 基本设置

2. 证书和描述文件

开发证书

发布证书

描述文件

3. 权限配置

4. Capabilities

图标和启动页

1. 应用图标

快速生成图标

2. 启动页

高级配置

1. 自定义资源

2. 自定义配置文件

3. 离线资源

配置文件示例

常见问题

包名冲突

签名验证失败

iOS 证书不匹配

图标显示异常

配置检查清单

下一步