Package Name — 什么是包名，反向域名表示法和要求

Android 中什么是 Package Name

Package Name — 是 Android 在操作系统层面用来标识应用程序的唯一字符串。它对应 AndroidManifest.xml 文件中的 package 字段和应用程序模块 build.gradle 文件中的 applicationId 字段。没有唯一的 Package Name，应用程序无法安装到用户设备上。

Package Name 的用途

在设备上，Package Name 充当管理应用程序的键：系统将每个应用程序的数据、设置和缓存存储在 /data/data/[packageName] 目录中。两个具有相同标识符的应用程序不能共存 — 尝试安装副本时，系统会建议删除现有应用程序。

Package Name 和 Application ID

在 Android Gradle Plugin 0.11+ 版本中，Package Name（在清单中）和 Application ID（在 build.gradle 中）之间出现了分离。Application ID 是系统和 Google Play 实际使用的应用程序标识符。清单中的 Package Name 用于资源解析和 R 类生成。为简单起见，建议保持它们一致。

// build.gradle（模块：app）
android {
    defaultConfig {
        applicationId "com.example.myapplication"
        minSdkVersion 24
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        debug {
            applicationIdSuffix ".debug"
        }
    }
}

applicationIdSuffix 字段允许为不同构建配置的 Application ID 添加后缀。Debug 版本可以具有 com.example.app.debug 标识符，从而允许将其与生产版本并排安装以进行并行测试。

Package Name 的命名规则

Google Play 为 Package Name 制定了严格的规则，必须在发布时遵守。标识符在整个商店范围内必须唯一，满足语法要求，并且不违反商标使用政策。

语法要求

Package Name 只能包含拉丁字母（A-Z, a-z）、数字（0-9）、点号（.）和下划线（_）。最大长度 — 150 个字符。点号之间的每个段必须以字母开头。连字符、空格和特殊字符被 Google Play 规则禁止。

唯一性要求

唯一性 是 Package Name 的绝对要求。如果其他应用程序已经使用了所选标识符，发布将被拒绝。Google 不会释放已删除应用程序的标识符，因此选择第一个 Package Name 对每个开发项目来说都是关键决定。

反向域名表示法和约定

反向域名表示法 — 是一种命名标准，其中公司域名以反向顺序书写：com.example 而不是 example.com。这样的系统保证了标识符的全局唯一性，因为每个域名本质上是唯一的。

标准前缀

开发人员通常使用与其域名 TLD 相对应的前缀：com 用于商业组织，org 用于非营利组织，io 用于技术项目，net 用于网络服务和解决方案。对于个人项目，允许使用 com.github.username 或 com.email。

• com.company.app — 商业应用程序的标准格式
• org.company.app — 用于非营利和开源项目
• io.company.app — 在初创公司和 SaaS 产品中流行
• com.github.username — 用于 GitHub 上的个人项目

跨平台项目的约定

对于在 iOS 和 Android 上发布的应用程序，建议在两个平台上使用相同的标识符。这简化了与 Firebase、AppsFlyer、Adjust 和其他绑定到项目标识符的分析系统的集成。例如，com.mycompany.myapp 在 iOS 上是 Bundle ID，在 Android 上是 Package Name。

在 Android 项目中配置 Package Name

配置 Package Name 在 Android 项目中包括更改 build.gradle 中的 applicationId 以及相应的 Java/Kotlin 代码目录结构。Android Studio 提供了重构 Package Name 的工具，但对于复杂项目，建议逐步迁移。

目录结构和 Package Name

// 文件路径对应 Package Name
// com/example/myapp/MainActivity.kt

package com.example.myapp

import android.os.Bundle
import androidx.activity.ComponentActivity

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

在 Kotlin 和 Java 中，源文件中的 Package Name 必须与目录结构对应。在 build.gradle 中更改 Package Name 时，需要将文件移动到相应的目录并更新所有 package 和 import 声明。Android Studio 可以通过 Refactor -> Move 自动完成此操作，但对于有数十个文件的大型项目，建议在重构后检查结果。

如果项目使用 Data Binding、View Binding 或 Hilt，更改 Package Name 还将影响生成的类。Binding 类基于模块的 Package Name 和布局目录创建。更改标识符后，需要重建项目以更新所有生成的引用。建议在更改 Package Name 后执行 clean build，以消除因缓存旧引用而导致的错误。

在 Gradle 7.0+ 中，build.gradle 中增加了对 namespace 的支持，它在生成 R 类和资源方面取代了 AndroidManifest.xml 中的 package。而 applicationId 仍然是系统和 Google Play 实际使用的应用程序标识符。这允许拥有不同的 applicationId 和 namespace，这对库模块很有用，其中 namespace 是固定的，而公共标识符可以在构建时更改。

对于具有 模块化架构 的项目，更改一个模块的 Package Name 可能会影响其他模块中的 import。如果 data 模块有 com.example.data 包，而 domain 模块使用其类，则在更改标识符后更新所有依赖模块中的 import。Android Gradle 插件 8.0+ 版本通过从 build.gradle 自动生成 namespace 简化了这一过程。

通过代码检查 Package Name

可以通过 BuildConfig 类获取当前的 Application ID：BuildConfig.APPLICATION_ID。这对于代码中的条件逻辑、绑定到环境或在调试屏幕上显示标识符非常方便。BuildConfig 基于 build.gradle 自动生成。

// 在运行时获取 Application ID
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

println("应用版本：${appInfo.versionName}（${appInfo.versionCode}）")
println("包：$packageName")

发布后更改 Package Name

更改 Package Name 在应用程序发布到 Google Play 之后 — 是一个意味着创建全新产品的操作。系统不允许使用不同的 Package Name 更新现有应用程序，因此更改标识符的决定相当于在商店中重新启动项目。

更改 Package Name 的后果

更改 Package Name 时会丢失：所有评分和评论、安装统计、Google Services 集成（如果未迁移）、Firebase 项目引用（需要创建新的 google-services.json）。用户不会收到自动更新 — 他们将在商店中看到一个新应用程序。

• 评分和评论 — 保留在旧应用程序中，不会转移
• 安装统计 — 对新的 Package Name 重置归零
• Firebase 项目 — 需要新的 google-services.json 配置和重新设置所有服务
• 用户 — 不会收到自动更新，需要单独通知

何时更改 Package Name 是合理的

更改 Package Name 可能在公司品牌重塑、将应用程序转移到另一个开发者帐户或为其他地区创建单独版本时是合理的。在任何情况下，在更改之前都建议通过旧应用程序通知用户，并准备带有数据迁移的迁移计划。没有迁移计划，用户将失去对已购买内容、订阅和保存的应用程序数据的访问。迁移包括通过 SharedPreferences 或 Room 迁移数据库和文件。

在更改 Package Name 之前，确保新标识符唯一且符合命名规则。在 Google Play 中使用新的 Package Name 创建新应用程序，并将其作为单独产品发布。在旧应用程序的描述中添加指向新应用程序的链接。考虑使用 Google Play Custom Store Listing 来重定向用户。