权限和依赖项

平台配置

平台特定的设置在清单中分组在 android 和 ios 键下。这使每个平台的所有配置保持在一起：

{
    "android": {
        "permissions": [...],
        "dependencies": {...},
        "repositories": [...],
        "activities": [...],
        "services": [...]
    },
    "ios": {
        "info_plist": {...},
        "dependencies": {...}
    }
}

权限

Android 权限

在 android.permissions 下以字符串形式列出 Android 权限：

{
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.RECORD_AUDIO",
            "android.permission.ACCESS_FINE_LOCATION"
        ]
    }
}

这些会在构建时添加到应用的 AndroidManifest.xml 中。

有关可用权限的完整列表，请参阅 Android Manifest.permission 参考。

iOS Info.plist 条目

iOS 需要每个权限的使用描述，以及你的插件需要的任何 API 密钥或配置令牌。在 ios.info_plist 下以键值对形式提供：

{
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "This app uses the camera for scanning",
            "NSMicrophoneUsageDescription": "This app records audio for transcription",
            "NSLocationWhenInUseUsageDescription": "This app needs your location",
            "MBXAccessToken": "${MAPBOX_ACCESS_TOKEN}"
        }
    }
}

这些会合并到应用的 Info.plist 中。你可以包括：

• 权限使用描述（NS*UsageDescription 键）
• API 令牌和配置密钥
• 你的插件需要的任何其他 Info.plist 条目

有关所有可用键，请参阅 Apple Information Property List 参考。

对敏感值（如 API 令牌）使用 ${ENV_VAR} 占位符。

注意

编写清晰、具体的使用描述。像"This app needs camera access"这样的通用消息可能导致 App Store 拒绝。解释为什么你需要该权限。

依赖项

Android 依赖项

在 android.dependencies 下添加 Gradle 依赖项：

{
    "android": {
        "dependencies": {
            "implementation": [
                "com.google.mlkit:face-detection:16.1.5",
                "org.tensorflow:tensorflow-lite:2.13.0"
            ]
        }
    }
}

这些会在编译期间添加到应用的 build.gradle.kts 中。你可以使用任何 Gradle 依赖类型：

• implementation — 标准依赖项
• api — 暴露给消费者
• compileOnly — 仅编译时
• runtimeOnly — 仅运行时

iOS 依赖项

CocoaPods

对于 CocoaPods 依赖项，使用 pods 数组：

{
    "ios": {
        "dependencies": {
            "pods": [
                {"name": "GoogleMLKit/FaceDetection", "version": "~> 4.0"},
                {"name": "TensorFlowLiteSwift", "version": "~> 2.13"}
            ]
        }
    }
}

每个 pod 对象接受：

• name — pod 名称（必需）
• version — 版本约束（可选，例如 ~> 4.0、>= 1.0）

NativePHP 在 iOS 构建过程中生成 Podfile 并运行 pod install。

Swift 包

对于 Swift Package Manager 依赖项：

{
    "ios": {
        "dependencies": {
            "swift_packages": [
                {
                    "url": "https://github.com/example/SomePackage",
                    "version": "1.0.0"
                }
            ]
        }
    }
}

优先使用 Swift 包

当库同时支持两者时，优先使用 Swift 包而不是 CocoaPods。它们集成更干净，构建更快。

自定义仓库

某些依赖项需要私有或非标准的 Maven 仓库（如 Mapbox）。在 android.repositories 下添加它们：

{
    "android": {
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    }
}

仓库配置：

• url — 仓库 URL（必需）
• credentials — 可选认证
  • username — 用户名或令牌名称
  • password — 密码或令牌（支持 ${ENV_VAR} 占位符）

这些会添加到应用的 settings.gradle.kts 中。

环境变量占位符

对敏感值使用 ${ENV_VAR} 语法。占位符在构建时替换为环境变量值。将此与 secrets 功能结合使用，以在构建前验证所需变量。

完整示例

这是一个使用 Mapbox 地图的 ML 插件的完整清单：

{
    "name": "vendor/ml-maps-plugin",
    "namespace": "MLMaps",
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.ACCESS_FINE_LOCATION"
        ],
        "dependencies": {
            "implementation": [
                "com.google.mlkit:object-detection:17.0.0",
                "com.mapbox.maps:android:11.0.0"
            ]
        },
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for real-time object detection",
            "NSLocationWhenInUseUsageDescription": "Location is used to display your position on the map",
            "MBXAccessToken": "${MAPBOX_PUBLIC_TOKEN}"
        },
        "dependencies": {
            "pods": [
                {"name": "MapboxMaps", "version": "~> 11.0"}
            ]
        }
    },
    "secrets": {
        "MAPBOX_DOWNLOADS_TOKEN": {
            "description": "Mapbox SDK download token from mapbox.com/account/access-tokens",
            "required": true
        },
        "MAPBOX_PUBLIC_TOKEN": {
            "description": "Mapbox public access token for runtime API calls",
            "required": true
        }
    }
}

官方插件和开发工具包

跳过配置复杂性——浏览现成的插件或获取开发工具包来构建你自己的。 访问 NativePHP 插件市场 →