Google 的 Android 开发文档中文版更新滞后，英文阅读门槛

Google 的 Android 开发文档中文版更新滞后，英文阅读门槛

Android 14 强制推行前台服务类型细分之后，我花了一个下午排查一个 RemoteServiceException: Bad foreground service: * doesn't have a valid foreground service type。应用 targeting API 34，代码里规规矩矩调了 startForeground()，Manifest 里也有 FOREGROUND_SERVICE 权限，结果在 Android 14 的真机上直接崩进程。去 developer.android.com 搜中文资料，页面里的内容还在讲 Android 9.0 开始需要申请 FOREGROUND_SERVICE 权限，对 Android 14 新加的 android:foregroundServiceType 属性只字未提。切到英文版，才发现服务类型已经从以前的笼统几种拆成了 camera、microphone、location、health、remoteMessaging、dataSync 等十几项，而且每一项都有严格的运行时权限映射关系。就这么一个文档时差，意味着只看中文文档的开发者根本没机会在编码阶段规避这个崩溃。

Android 14 前台服务限制：中文文档的真空地带

Android 14 在 2023 年 Google I/O 上就把前台服务的权限收紧作为 headline feature 之一公布了。官方英文文档在 Behavior changes: Apps targeting Android 14 页面里写得极其清楚：如果你在 targetSdkVersion 34 的应用里启动前台服务，必须在 Manifest 的 <service> 标签里声明 android:foregroundServiceType，否则系统会抛异常终止服务。更细的是，如果你声明了 health 类型，用户必须在设置里授予 ACTIVITY_RECOGNITION 或者 BODY_SENSORS 权限；声明了 remoteMessaging，则需要确保已经拿到通知权限或者相关网络权限。这套规则在英文文档里是一张完整的矩阵表。

而中文文档在相当长一段时间里，关于前台服务的页面还停留在旧版本。它告诉你需要 FOREGROUND_SERVICE 权限，需要调用 startForeground() 传入通知 ID 和 Notification 对象，但完全没提服务类型声明。开发者照着中文文档写代码，IDE 不会报错，因为 foregroundServiceType 在 XML 里是合法属性但不是编译期强制项，运行时到 Android 14 设备上才炸。这种坑最阴的地方在于：测试机如果是 Android 13，一切正常；一上 Android 14 的线上用户，就大面积崩溃。Google 不是没有在英文世界给出预警，它只是没把预警同步到中文文档里。这种滞后的代价，完全由国内开发者承担。

Jetpack Compose 文档里的语义漂移

Compose 的中文文档问题更隐蔽，不是缺内容，而是翻译失真。拿 derivedStateOf 来说，英文原文在 State 和 Jetpack Compose 页面里强调：如果你要根据一个高频变化的状态计算另一个派生状态，必须用 derivedStateOf，因为它能保证只有计算结果真正改变时才会触发重组，而不是每次上游状态变化都重组。这个性能语义是核心。中文文档把它翻译成"当您的状态依赖于其他状态时使用"，轻飘飘一句话，把"避免不必要重组"这个关键动机给吞掉了。

结果国内很多 Compose 教程（很多作者本身也是看中文文档入门）就开始滥用 remember + by。我见过有人在 LazyColumn 的滚动状态监听里直接用 val firstVisibleItem by remember { derivedStateOf { listState.firstVisibleItemIndex } } 这种其实写错了上下文的代码，但更多人连 derivedStateOf 都不晓得用，直接在 Composable 里做 val filtered = list.filter { ... }，每次列表状态变化都全量过滤重组。追根溯源，英文文档里反复出现的 "expensive calculation" 和 "unnecessary recomposition" 在中文翻译里被弱化成了"计算"和"重组"，语义漂移导致整个技术社区的认知起点就偏了。

还有 rememberSaveable。中文文档说它是"在配置变更后保存状态的 remember"。这个翻译表面上没错，但没提 Bundle 的 size limit，没提它默认要求状态实现 Parcelable 或 Serializable，也没提 Saver 和 MapSaver 的自定义方式。英文文档里专门有一节讲 "RememberSaveable and process death"，中文要么缺失，要么藏在页面底部。开发者用 rememberSaveable 存一个大型对象，应用因进程死亡恢复时直接 TransactionTooLargeException，去搜中文资料根本找不到解释。

Material3 迁移指南的时差

Material3 从 androidx.compose.material3:material3:1.0.0 到 1.1.0 再到 1.2.0，API 变动极大。BottomSheetScaffold 在 1.1 里整个参数结构重写了，英文文档有专门的 Migration 页面，把 sheetPeekHeight、sheetContent 的改动列得清清楚楚。中文版的