如果你的应用已经在生产轨道上进行了分阶段发布，想要把当前10%的用户分发比例提升到50%，通常的做法是打开Play Console，找到发布概览，拖动滑块然后保存。但如果你需要频繁调整、定时放量，或者在CI/CD流水线中自动完成发布，手动操作就变成了一种负担。Play Developer API 提供了一套编辑机制，允许开发者通过接口动态更新生产轨道的 userFraction 字段，从而实现分发比例的自动化管理。接下来会介绍具体的实现步骤和注意事项。
生产轨道与分阶段发布的基础概念
在Google Play Console中，每个应用都有多个发布轨道：内部测试、封闭测试、开放测试、生产轨道。生产轨道上的发布可以是完整的全量发布，也可以是分阶段发布。分阶段发布允许开发者先向一部分用户推送新版本，观察崩溃率、评分和关键指标，再逐步扩大范围。对于已经上线并积累了一定用户量的应用，这种渐进式放量可以显著降低因新版本缺陷导致的大面积用户流失风险。
在Play Developer API v3中，生产轨道的发布信息通过 edits().tracks().get() 方法获取。返回的 track 对象里有一个 releases 数组，数组中的每个元素代表一个发布。对于分阶段发布，发布对象中有一个 userFraction 字段，取值范围是0到1之间的浮点数，表示目标用户比例。例如0.1表示10%的用户会收到这个版本。状态字段 status 可以是 completed、inProgress、halted 或 draft。动态调整分发比例实际上就是在修改 userFraction 和 status。
需要留意的是，一个轨道上可能同时存在多个发布，例如正在滚动的发布和已完成的旧版本。调用更新时通常需要定位到当前 status 为 inProgress 的发布。如果直接修改整个 releases 数组，可能会意外覆盖其他发布，所以更稳妥的做法是先读取、找到目标发布、修改后再整体写回。这样可以避免因为只提交部分字段而破坏原有的发布配置。
使用 Play Developer API 修改分发比例
开始之前需要满足几个条件：在 Google Cloud Console 启用 Android Publisher API，创建服务账号并下载 JSON 密钥文件，然后在 Play Console 的用户和权限页面里给这个服务账号授予发布权限。完成授权后，可以使用 Google 提供的 Python 客户端库来简化调用。安装依赖的命令是 pip install google-api-python-client google-auth，官方文档也提供了 Java、Node.js 等语言的客户端库。
下面是一个完整的 Python 示例，演示如何把生产轨道上正在进行的分阶段发布的比例调整为50%。代码中先创建一个编辑会话，获取当前生产轨道信息，找到正在进行的发布，更新 userFraction 和 status，最后提交编辑。整个过程全部通过 API 完成，不需要登录 Play Console。
from googleapiclient.discovery import build
from google.oauth2 import service_account
SERVICE_ACCOUNT_FILE = 'service_account.json'
SCOPES = ['https://www.googleapis.com/auth/androidpublisher']
credentials = service_account.Credentials.from_service_account_file(
SERVICE_ACCOUNT_FILE, scopes=SCOPES)
service = build('androidpublisher', 'v3', credentials=credentials)
package_name = 'com.example.app'
# 创建编辑会话
edit_id = service.edits().insert(packageName=package_name).execute()['id']
# 获取生产轨道信息
track = service.edits().tracks().get(
packageName=package_name,
editId=edit_id,
track='production'
).execute()
# 找到正在分阶段发布的版本
for release in track.get('releases', []):
if release.get('status') == 'inProgress':
release['userFraction'] = 0.5
break
else:
raise RuntimeError('未找到正在分阶段发布的版本')
# 写回生产轨道
service.edits().tracks().update(
packageName=package_name,
editId=edit_id,
track='production',
body=track
).execute()
# 提交编辑，使修改生效
service.edits().commit(
packageName=package_name,
editId=edit_id
).execute()
print('生产轨道分发比例已更新为 50%')
上面的代码里，track 对象是被整体回传的，这能保留其他没有动过的字段。修改 userFraction 后，Play 会按照新的比例继续扩大分发。如果希望暂停分发而不是调整比例，可以把 status 改为 halted，这样已安装的用户不会受影响，但新用户不会再收到这个版本。暂停后还可以随时重新启动，只需把状态改回 inProgress 并设置新的比例。
在实际项目中，建议把这段逻辑封装成一个函数，接收比例参数，方便 CI/CD 调用。例如在发布流水线中每天自动增加5%的比例，并设置一个最大阈值，超过后自动全量发布。还可以结合应用内崩溃率指标，用脚本判断是否继续放量或紧急暂停，形成自动化可控的发布流程。这样既减少了人工操作，又让发布策略可以基于实时数据动态调整。
常见问题与最佳实践
动态调整分发比例最常见的坑是编辑会话没有提交。Play Developer API 的 edits 是事务性的，所有对轨道、APK、商品信息的修改都必须通过 commit() 提交才会真正生效。如果只调用 update() 而忘记提交，或者进程在提交前崩溃，修改就会丢失。另一个问题是并发编辑：如果多个服务同时操作同一个包名，后提交的一方可能覆盖先提交的改动。建议在服务端用锁或队列来串行化编辑操作。
权限方面，服务账号必须在 Play Console 中被添加为管理员或具有发布权限的账号，否则调用会返回 403 错误。服务账号的密钥文件要妥善保管，不要提交到代码仓库。更安全的做法是在 CI 环境中使用环境变量或密钥管理服务注入凭据。此外，API 调用有配额限制，频繁轮询或调整可能会触发限流，需要实现指数退避和重试逻辑，避免因为短时间大量请求导致自己的服务被临时封禁。
如果更新后想要验证结果，可以再次调用 edits().tracks().get() 读取生产轨道，确认 userFraction 已经变为预期值。也可以检查 releases 数组中的 status，确保没有出现 halted 状态。对于需要快速回滚的场景，可以保留旧的编辑 ID 或重新创建一个编辑会话，将 userFraction 调回原来的比例，或者把 status 改为 completed 全量发布。自动化发布的同时，建议保留人工审核开关，防止异常情况下自动放量失控。
Play Developer API生产轨道用户分发比例修改时间：2026-10-03 12:43:32