企业官网建设流程全解析

我手上那台备用机在Android 11正式版推送当天就升了上去，本来只是想看看新版本长什么样，结果一跑自家的应用，三个崩溃、两个功能静默失效。那一晚我把日志翻到凌晨两点，才彻底意识到一件事：这次升级对普通用户来说是"更好用了"，对开发者来说却是"该还债了"。Android 11把前几年一直挂在"建议"名单里的东西集体转正——分区存储强制、权限模型再收紧、包可见性生效、前台服务类型必须声明，每一条都直接落在targetSdkVersion这根线上。你不动它，应用照跑；你一动，问题全出。

这篇内容我想聊的就是Android 11 正式版落地之后，开发者该按什么顺序去啃这块骨头。它不面向零基础教程，也不太适合只想看看新特性截图的人，更适合手上有一个已经上架、用户量还行、正在纠结要不要把 targetSdk 提到 30 的一线开发。我会按我自己踩坑的顺序来写：先讲存储和权限这两块最要命的，再讲通知气泡这类交互改动，然后是无线调试和增量安装这种能立刻提升日常效率的工具，最后落到包可见性、前台服务类型这些"不声明就悄悄出问题"的坑，以及一套我实际用过的适配节奏。代码片段都是能直接抄的，参数计算和取舍逻辑我会说清楚为什么。看完你应该能自己排出一张适配清单，而不是对着一堆官方文档发愁。

1. 分区存储从"建议"变成强制执行

分区存储这个概念从 Android 10 就开始提，但那年它给了个台阶——requestLegacyExternalStorage="true"，只要在清单里写上这一行，应用就能继续用老的WRITE_EXTERNAL_STORAGE那套路径直读直写。这个台阶让相当多的团队选择了"先不动，明年再说"。Android 11 就是这个"明年"。当targetSdkVersion提到 30 之后，那个开关的效果直接归零，系统按新的规则走：应用只能在属于自己的目录、公共媒体集合（通过 MediaStore）、以及用户手动授权的目录里操作文件。你原来那些/sdcard/你的应用名/xxx的硬编码路径，会开始返回权限拒绝或者干脆写不进去。

1.1 为什么这个开关必须失效

从系统设计的角度看，这个决定其实没什么可商量的余地。老的外部存储模型是"一次授权，全盘通行"——用户给了存储权限，应用就能遍历整个外部存储，读别的应用留下的文件、改动别人的缓存。这套模型在早期存储容量小、应用少的年代还能凑合，后来变成什么样子，做过文件管理类功能的人都清楚：目录里堆满了各种应用自己建的、命名风格各异、删了还要担心影响别人的文件夹。分区存储要解决的是归属权和生命周期的归属——每个应用写的数据，系统能明确知道是谁写的，卸载时能干净地清掉，别的应用想读就得走系统这层"中介"，而中介是可以审计、可以弹确认框的。

从开发者角度，理解这一点比记住 API 更重要。很多人迁移的时候只是把路径换掉，思维还停留在"我要找个地方存文件"。正确的思路是：先问这个文件属于谁。属于我自己的私有数据，走context.getExternalFilesDir()或者干脆filesDir，这些路径不需要任何权限，卸载即清；属于要分享给其他应用或用户的媒体文件，走 MediaStore 的公共集合；属于用户自己选定的目录（比如让他挑一个文件夹备份），走 SAF 的ACTION_OPEN_DOCUMENT_TREE拿持久化 URI 权限。三条路走对了，后面基本不会碰壁。

1.2 迁移的实操路径：从 MediaStore 写入开始

我自己的迁移是从最痛的地方切入的——图片导出。原来是把 Bitmap 压缩后直接FileOutputStream写到外部存储，现在得改成 MediaStore 插入。关键点在于IS_PENDING这个标记，它的作用是"文件已经创建但还没写完，别人别读"。这个设计很实在，避免了其他应用在你写到一半时扫到这个残缺文件。写完之后把IS_PENDING置回 0，文件才正式可见。

suspend fun saveImageToGallery( resolver: ContentResolver, bitmap: Bitmap, displayName: String ): Uri? = withContext(Dispatchers.IO) { val values = ContentValues().apply { put(MediaStore.Images.Media.DISPLAY_NAME, displayName) put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg") put(MediaStore.Images.Media.RELATIVE_PATH, "${Environment.DIRECTORY_PICTURES}/MyAppExport") put(MediaStore.Images.Media.IS_PENDING, 1) } val uri = resolver.insert( MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values ) ?: return@withContext null try { resolver.openOutputStream(uri)?.use { out -> bitmap.compress(Bitmap.CompressFormat.JPEG, 92, out) } values.clear() values.put(MediaStore.Images.Media.IS_PENDING, 0) resolver.update(uri, values, null, null) uri } catch (e: Exception) { resolver.delete(uri, null, null) null } }

这段代码有几个细节值得单独说。RELATIVE_PATH指定的相对目录，系统会自动帮你建，不需要自己mkdirs；它必须以标准集合名开头，比如Pictures、DCIM、Download，写成别的会被拒绝。压缩质量我用 92，是因为导出用户拍摄的照片时，低于 90 肉眼能看出边缘发糊，而 100 又会让文件体积翻倍，92 是个实测下来平衡点比较舒服的值。异常分支里要记得删掉那条IS_PENDING=1的记录，否则会留下一堆"幽灵文件"——用户在图库里看不到，但实际占着空间，这个问题我在测试机上攒过二百多条才被发现。

1.3 修改和删除他人媒体的正确姿势

Android 11 给 MediaStore 加了一组"批量操作请求"的 API，这是很多人迁移时会踩的坑。以前应用删除自己写的文件是自由的，但如果是用户通过你的应用去删他自己图库里的照片（比如清理重复照片这类功能），targetSdk 30 之后就不行了，必须走MediaStore.createDeleteRequest()。调用之后系统会弹一个确认框，用户点同意，你的应用才拿到这批 URI 的临时写权限。

val urisToDelete: List<Uri> = collectDuplicatePhotos() val pendingIntent = MediaStore.createDeleteRequest(resolver, urisToDelete) launcher.launch(IntentSenderRequest.Builder(pendingIntent.intentSender).build())

同理还有createWriteRequest()用于批量修改、createTrashRequest()送到回收站（30 天可恢复）、createFavoriteRequest()标记收藏。这些 API 的价值不只是合规——它把"用户知情"这件事真正做进了流程里。我个人的判断是，凡是涉及用户相册的操作，都应该主动走这套流程，哪怕某些路径上你还有可能绕过去。用户对相册的敏感度远高于其他数据，一个"悄悄删照片"的差评足以抵消几个版本的功能积累。

注意：MANAGE_EXTERNAL_STORAGE这个"所有文件访问权限"不要当成救命稻草。它需要单独申请且在应用商店侧有严格的用途审核，文件管理器、杀毒、备份这类工具类应用才说得过去。普通应用申请大概率被拒，还会拖慢审核周期。

2. 权限收紧的三板斧：一次性授权、闲置重置、后台定位

Android 11 的权限改动，表面上只是加了几个新选项，实际影响的是整个权限请求的时序设计。我见过不少项目在升级后出现"权限明明申请了但功能就是不工作"，追下去多半是这三条里的一条没处理好。它们分别是：一次性授权、长期未使用自动重置、后台定位必须单独跳设置页申请。这三条任何一条没适配，都会在特定用户路径上炸出问题，而且因为是"部分用户部分场景"，测试阶段很难覆盖全。

2.1 "仅本次允许"打断了"授权一次用一年"的假设

位置、麦克风、相机这三个权限，现在多了一个"仅本次允许"选项。用户选了这个，应用退到后台一段时间后，权限自动回收。这意味着你原来那种"启动时申请一次，之后所有功能都默认有权限"的写法，会在用户从最近任务里划掉应用再打开时突然失效。

处理思路上我做了两件事。第一，把权限检查从"启动时一次性"改成"使用前检查"，尤其是相机和麦克风这种有明确动作触发的，在用户点拍摄按钮的那一刻判断，没有就再请求，而不是假设它一直在。第二，把shouldShowRequestPermissionRationale()的返回值利用起来，用来区分三种状态：从没问过、问过被拒但还能再问、问过且勾了不再询问。Android 11 里这个 API 还多了一个用途——当用户选了"仅本次允许"，再问的时候它不会返回 true，因为系统认为你已经拿到了权限，只是临时的。所以不能用它来判断"当前有没有权限"，权限判断还是要老老实实走checkSelfPermission()。

fun needRequestCamera(activity: Activity): Boolean { val granted = ContextCompat.checkSelfPermission( activity, Manifest.permission.CAMERA ) == PackageManager.PERMISSION_GRANTED if (granted) return false // 返回 true 说明用户拒绝过但没勾选不再询问 // 返回 false 可能是首次，也可能是永久拒绝，需要结合 shouldShow 之外的信息 return true }

2.2 后台定位为什么不能再靠弹框解决

这是升级过程中最容易卡住的一条。Android 10 的时候，前后台定位还能在同一个权限对话框里一起申请，用户点一次就都给了。Android 11 开始，ACCESS_BACKGROUND_LOCATION不能再通过requestPermissions()弹出来，你必须引导用户进入系统设置页，手动把位置权限从"仅在使用时允许"改成"始终允许"。

官方给的路径是ACTION_APPLICATION_DETAILS_SETTINGS跳到应用详情页，或者用 Android 11 新增的ACTION_APPLICATION_DETAILS_SETTINGS加包名精确跳转，甚至可以尝试直接跳到位置权限那一屏（部分定制系统支持）。我的做法是：在真正需要后台定位之前（比如用户开启了"轨迹记录"开关），弹一个自己写的说明页，讲清楚为什么需要、会怎么用、不给会怎样，然后给一个按钮跳设置。跳过去之后，回来用onResume再检查一次状态，给不同的反馈。

提示：不要一进应用就要后台定位。系统本身对频繁请求后台定位的应用有频率限制，而用户体验上，一上来就要求"始终允许"的授权率非常低。把请求时机推到功能触发点，授权率能翻好几倍，这是我在两个项目上对比过的实测结果。

2.3 权限适配速查表

"闲置自动重置"这条我要多说一句。系统会把几个月没打开过的应用的运行时权限自动收回。这个机制对用户是好事，但对那些"装了就不常打开、靠后台同步工作"的应用是个隐形炸弹——用户某天打开，发现数据没同步，其实是因为权限被重置了，而应用在启动时没有做权限校验就直接跑同步逻辑，静默失败。我的处理是：在应用启动的初始化流程里，对所有关键权限做一次checkSelfPermission，缺了就进一个"需要重新授权"的引导页，而不是让它悄悄降级。这个改动量不大，但能省掉大量"我的数据不同步"的客服问题。

3. 通知与气泡：会话类应用的交互重构

通知这一块在 Android 11 里的变化，不仔细看容易忽略，因为它不是"新增功能"那种显眼的改动，而是把已有的东西往更细的方向推了一步。两个变化值得单独拎出来：一是对话通知（Conversation）被系统单独分类并置顶，二是气泡（Bubbles）从开发者选项里转正成了正式能力。如果你的应用有消息、评论、客服、社交这类场景，这两块基本躲不开。

3.1 对话通知的判定条件比想象中严格

系统要判断一条通知是不是"对话"，靠的是通知里有没有MessagingStyle，以及有没有绑定一个可识别的人。它不会因为你的标题里写了个用户名就认。

val person = Person.Builder() .setName(senderName) .setIcon(avatarIcon) .setImportant(true) .build() val style = Notification.MessagingStyle(person) .setConversationTitle(conversationName) .addMessage(text, timestamp, person) NotificationCompat.Builder(context, CHANNEL_ID) .setStyle(style) .setShortcutId(conversationId) // 关键，缺了它对话区不会收录 .setSmallIcon(R.drawable.ic_msg) .build()

setShortcutId()这一行是最容易漏的。没有它，通知能正常显示，但不会被归到对话区，也就享受不到置顶、免打扰单独控制这些待遇。另外要注意，Person的setImportant(true)影响的是系统对这个人消息的优先级判断，别乱设，全员 important 等于全员不重要。

还有一个实操细节：对话通知的排序和"已读回执"有关。如果你的应用支持已读状态，记得在用户读完消息后及时cancel()对应的通知，否则系统会认为这个对话一直是未读状态，长期占着对话区顶部，用户会觉得烦。

3.2 气泡的落地条件与实测踩坑

气泡这个交互，做得好是效率工具，做不好就是骚扰。Android 11 里它的启用条件我梳理了一下，缺一条都弹不出来：

1. 通知必须使用MessagingStyle；
2. 必须通过setBubbleMetadata()挂上气泡元数据；
3. 目标 Activity 必须支持resizeableActivity，并且launchMode要处理好，否则点开气泡会重建整个任务栈；
4. 需要用户侧在系统设置或长按通知里主动开启，应用无法强制弹出。

val bubbleIntent = PendingIntent.getActivity( context, 0, Intent(context, ChatActivity::class.java).apply { putExtra("conversation_id", conversationId) }, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE ) val bubbleData = NotificationCompat.BubbleMetadata.Builder( bubbleIntent, IconCompat.createWithBitmap(avatar) ) .setDesiredHeight(600) .setAutoExpandBubble(false) .build() builder.setBubbleMetadata(bubbleData)

setAutoExpandBubble(false)这个选择值得解释一下。设成 true 意味着通知一来气泡就自动展开，覆盖在用户当前操作之上。这个行为在聊天应用里可能合适，但在客服、评论回复这类场景里非常打断。我倾向于设 false，让用户自己决定要不要展开。

实测里最坑的一点是气泡数量限制。同一个应用最多同时存在 5 个气泡，超出的会被收进一个折叠的栈里。如果你的应用会为每个会话创建一个气泡，用户消息一多，体验会迅速崩塌。所以我在设计时加了个约束：只给"当前活跃会话"（比如用户主动置顶的、或者最近 10 分钟内有往来的）创建气泡，其他一律走普通通知。

注意：气泡在小屏设备上展开后会占据大半屏幕，测试时一定要覆盖小屏和横屏两种场景。我在一台 5 英寸的老机器上测出过气泡内输入框被软键盘完全遮挡的问题，改法是给气泡 Activity 加上windowSoftInputMode="adjustResize"并监听 insets 变化。

4. 无线调试与增量安装：日常联调的效率提升

这两项放在一起说，是因为它们不影响线上功能，但对日常开发效率的改变非常直接。我原来调真机，桌面上永远插着两三根线，换个设备就得拔插一次；现在一根线都不用，配对好之后直接在终端里连。增量安装则是把"装一个 200MB 的包等半分钟"这件事压缩到了一个可以接受的范围。

4.1 无线调试配对的完整流程与失败排查

开启路径在开发者选项里，叫"无线调试"。打开之后会看到一个配对码和端口，注意这里有个容易搞混的地方：配对端口和连接端口不是一个。配对用的是屏幕弹窗里显示的那个端口，配对成功后连接用的是主界面上那个 IP:端口。

# 第一步：配对，端口来自弹窗中的"使用配对码配对设备" adb pair 192.168.1.23:37105 # 按提示输入 6 位配对码 # 第二步：连接，端口是无线调试主界面显示的那个 adb connect 192.168.1.23:40501 # 验证 adb devices

我用下来最常见的三类失败：

• 两台设备不在同一网段。电脑连着 5G 频段、手机连着 2.4G，路由器如果做了频段隔离就通不了。这种情况换到同一 SSID 基本能解决。
• 配对成功但连不上。多数是端口记错了，或者手机上把无线调试关掉重开导致端口变了。重启一次无线调试，重新看端口号。
• adb 版本太老。adb pair命令需要平台工具 30.0.0 以上，版本不够会直接报 unknown command。升级一下就行，这个错误提示还算明确。

还有一个实用技巧：无线调试在部分设备上息屏后会断，可以在开发者选项里配合"充电时不锁定屏幕"一起用。我自己的习惯是把测试机常插在充电器上，息屏策略设为不锁屏，一整天下来连接都很稳。

4.2 增量安装的收益与限制

Android 11 支持的增量安装，原理是把 APK 的安装过程改成流式读取——系统只加载运行所需的块，其余部分在后台继续传输。对本地开发来说，最直观的变化是adb install加一个参数就能启用：

adb install --incremental app-release.apk

实测数据：一个 180MB 的包，普通安装在我的测试机上要 26 秒左右，增量安装首次启动可以压到 6 秒出头，剩下的在后台补齐。这个差异在需要反复安装调试的下午会被无限放大。

不过限制也要说清楚，不然容易白折腾：

我的建议是把增量安装定位成"本地调试加速手段"，正式发布流程照旧。CI 上也可以用，但要先确认打包链路里的签名和对齐没被跳过——不少项目为了包体积把 v2 签名配得很随意，一开增量安装就报错，问题还不好定位。

5. 包可见性、前台服务类型与新 API 的取舍

前面几块是"必须改"，这一块是"不改会出玄学问题"。Android 11 引入了包可见性（Package Visibility）机制，同时要求前台服务必须声明类型。这两条的共同点是：不声明不会报编译错误，运行时也不会立刻崩，但功能会静默失效或者被系统杀掉。这类问题最消耗排查时间，所以我把它单独列出来。

5.1 queries 标签：看不见的崩溃源头

从 targetSdk 30 开始，应用默认只能看到自己、以及跟自己有交互的少数几个包。你调queryIntentActivities()、getPackageInfo()、getInstalledPackages()这些 API，返回结果可能只剩自己。这个设计初衷是限制应用随意扫描设备上装了什么，但对分享、支付、地图这类需要判断"目标应用在不在"的场景影响很大。

解决方式是在清单里声明<queries>：

<queries> <!-- 按 intent 声明：我需要能处理"查看网页"的应用 --> <intent> <action android:name="android.intent.action.VIEW" /> <data android:scheme="https" /> </intent> <!-- 按包名声明：我需要跟这个具体的应用交互 --> <package android:name="com.example.partner.pay" /> </queries>

我的经验是优先用<intent>声明，因为它表达的是"能力需求"而不是"点名某个应用"，扩展性更好，也不会因为合作方换包名就失效。只有确实需要跟特定应用做深度集成（比如约定的协议、共享的 provider）时，才用<package>。

排查技巧：如果升级后发现分享面板里少了选项、支付跳转失败但没报错，先在清单里搜queries，八成是没有。可以在代码里加一行日志打印packageManager.queryIntentActivities(...)的返回数量，和升级前对比，差异会非常明显。

5.2 前台服务类型必须显式声明

targetSdk 30 之后，启动前台服务时如果没在清单里声明类型，会抛MissingForegroundServiceTypeException。这个还算友好，至少给你一个明确的异常。麻烦的是声明了类型但用错了——比如把上传任务声明成mediaPlayback，系统在某些场景下会限制或者杀掉服务。

<service android:name=".sync.UploadService" android:foregroundServiceType="dataSync" android:exported="false" />

常用类型和对应场景：

启动时还要注意，Android 11 对"从后台启动前台服务"的限制更严了。应用在后台时想拉起前台服务，需要满足特定豁免条件（比如用户刚有过交互、或者有高优先级通知）。我的处理方式是把启动时机尽量前置到 Activity 可见的时候，而不是等一个延迟任务在后台触发。

5.3 值得优先接入的几个新能力

新 API 里我实际用了并且觉得有价值的，主要是两个。

设备控制（Device Controls）。Android 11 的长按电源菜单里集成了一个设备控制区，应用可以通过实现ControlsProviderService把智能家居、车机、IoT 设备的开关放进去。接入成本不算低，需要实现一个 Service 并声明对应的 intent filter，但如果你的应用本身就管着一堆设备，这个入口的便利性很高——用户不用打开应用就能开关灯。

<service android:name=".controls.DeviceControlService" android:exported="true" android:permission="android.permission.BIND_CONTROLS"> <intent-filter> <action android:name="android.service.controls.ControlsProviderService" /> </intent-filter> </service>

软键盘动画与 insets 适配。WindowInsetsAnimation让应用能跟着键盘的动画曲线一起动，而不是等键盘完全弹起后突然跳一下。配合setDecorFitsSystemWindows(false)使用，输入框跟随键盘平滑上移的体验提升非常明显。代价是要自己处理 insets 分发，代码量增加，而且老版本要写兼容分支。我的做法是只在新版本走新逻辑，老版本保留原来的adjustResize，用Build.VERSION.SDK_INT分流，避免在低版本上引入不确定性。

ViewCompat.setOnApplyWindowInsetsListener(rootView) { v, insets -> val ime = insets.getInsets(WindowInsetsCompat.Type.ime()) val sys = insets.getInsets(WindowInsetsCompat.Type.systemBars()) v.updatePadding(bottom = maxOf(ime.bottom, sys.bottom)) insets }

6. 适配节奏与线上问题排查实录

写到这儿，前面讲的都是"改什么"，这一节讲"怎么排期"。targetSdk 从 28 一步跳到 30 是我见过最常见的翻车方式，改完一上线，各种边角问题集中爆发，回滚都来不及。我自己用过一轮比较稳的推进节奏，分成三个阶段。

6.1 从 28 到 30 的分阶段推进

第一阶段只做"不提升 targetSdk 也能做的适配"。比如把文件路径访问逻辑抽成一层封装、把权限检查统一到一个工具类、给所有queryIntentActivities调用加上兜底。这个阶段风险最低，因为行为还没变，只是代码结构变了，出问题容易回退。

第二阶段把 targetSdk 提到 29，先吃掉 Android 10 的遗留问题。这时候分区存储已经生效（除非你还留着 legacy 开关），但包可见性和前台服务类型还没强制。把它跑一段时间，收集线上崩溃和功能异常，稳定之后再动。

第三阶段才是提到 30。上之前我会做一个清单核对：存储路径是否全部走 MediaStore 或 SAF、后台定位是否有引导页、清单里queries是否补齐、前台服务类型是否声明、requestLegacyExternalStorage是否已经删掉。这五项全部打勾，才有底气推。

提示：不要指望一次灰度就能发现问题。我的经验是按 5%、20%、50%、全量四档推，每档至少观察两天，重点看崩溃率、权限相关的客服工单量、以及涉及文件的功能成功率。权限问题往往不是崩溃，而是"功能没反应"，只靠崩溃监控是看不到的。

6.2 常见问题速查表

下面这张表是我和团队在适配过程中真实遇到并解决过的问题，按现象倒查原因，节省了不少时间。

表里第三行我想额外说一句。前台服务被系统杀掉的日志，往往不会直接告诉你"因为类型不对"，而是给一个比较笼统的 ANR 或者进程死亡记录。定位方法是把这个服务的启动日志、startForeground()调用时机、以及系统的ActivityManager相关日志放在一起看时间线。有一次我们排查了整整一天，最后发现是startForeground在onCreate里调用得太晚，超过了 5 秒窗口，跟类型声明没关系。

6.3 灰度期间值得盯的几个指标

功能成功率比崩溃率更能反映适配问题。我在灰度阶段会额外加几个埋点：文件保存成功率、权限授予率（按权限类型分）、分享面板唤起成功率、前台服务存活时长。这几个数字在升级前后的对比，比任何日志都直观。

权限授予率这一项特别有参考价值。如果升级后发现后台定位的授予率从 40% 掉到了 5%，那基本可以确定是引导页设计有问题，或者跳转的页面不对——用户点进去找不到"始终允许"在哪，就退出来了。我后来的做法是在引导页里放一张截图，标出该点哪里，授予率回升到了 25% 左右。这事儿说起来有点土，但确实有效。

另外建议在设置页里加一个"权限状态自检"入口，把所有关键权限的当前状态列出来，用户遇到问题时能自己看一眼，减少客服压力。这个功能实现成本很低，收益却超出预期。

最后分享一个我自己的习惯：每次大版本适配，我都会在测试机上保留一个"纯净环境"——不装任何其他应用、不清缓存、权限全部重置过。很多权限和存储的问题只在全新安装的路径上出现，升级安装的机器因为历史状态还在，反而看不出来。这个纯净环境帮我抓到了至少三个只在首次启动时才会触发的 bug。适配这件事，说到底不是把文档上的条目一条条勾完，而是要把自己放到"一个刚买了新手机、第一次装你应用的用户"的位置上，把每条路径都重新走一遍。