需求分析先想清楚哪些页面需要单独适配哪些跟系统色走就行哪些组件有硬编码色值需要替换。这一步直接决定后面代码改动范围和测试工作量。关键结论暗黑模式不是简单换几个色值而是一套完整的配色体系和层级关系都要重新梳理。我见过不少团队以为改几个#333就完事了结果隔天测试跑来看整个界面灰蒙蒙一片对比度严重不足。设计对接跟设计同学明确语义色规则背景、前景、填充、分隔线各自对应哪几个层级这一步别省否则后面每张图、每个控件都来问你要色值你会疯。控件自检逐个页面过一遍UI控件清单拿不准的先标记后面逐步验证。主背景Background页面最底层的基础底色次级背景Secondary Background卡片、分组列表的底色三级背景Tertiary Background弹窗、浮层底部的底色主文本Primary Label一级信息文本、标题、正文核心次级文本Secondary Label辅助说明、次要信息三级文本Tertiary Label占位符、时间戳、弱化信息分隔线Separator列表分隔线、边框主控件填充Primary Fill按钮、开关等主要控件的填充色次级控件填充Secondary Fill次要控件的填充色警示色System Red/Orange/Yellow等错误、警告、成功状态// 错误示范硬编码色值 self.view.backgroundColor [UIColor colorWithRed:0.96 green:0.96 blue:0.96 alpha:1.0]; // 正确姿势使用系统语义色 self.view.backgroundColor [UIColor systemBackgroundColor];打开 Assets.xcassets在左侧栏底部点“”号新建 Color Set右侧属性面板中在 Appearance 一栏选 Any Appearance 和 Dark分别设置 Any浅色和 Dark深色模式下的色值代码里直接通过[UIColor colorNamed:AppBackgroundColor]调用// 代码调用Assets颜色 self.view.backgroundColor [UIColor colorNamed:AppBackgroundColor]; // Swift写法 view.backgroundColor UIColor(named: AppBackgroundColor)// 动态Provider写法 (UIColor *)appThemeColor { return [UIColor colorWithDynamicProvider:^UIColor *(UITraitCollection *traitCollection) { if (traitCollection.userInterfaceStyle UIUserInterfaceStyleDark) { return [UIColor colorWithRed:0.11 green:0.11 blue:0.13 alpha:1.0]; } return [UIColor colorWithRed:0.96 green:0.96 blue:0.96 alpha:1.0]; }]; }// 关闭暗黑模式的旧做法已被Apple官方建议逐步弃用 - (UIUserInterfaceStyle)overrideUserInterfaceStyle { return UIUserInterfaceStyleLight; }// 视图控制器级别强制 self.overrideUserInterfaceStyle UIUserInterfaceStyleDark; // 整个窗口级别强制 self.window.overrideUserInterfaceStyle UIUserInterfaceStyleDark;// 用带Luminosity的动态色替代 UIColor *navColor [UIColor colorWithDynamicProvider:^UIColor *(UITraitCollection *traitCollection) { if (traitCollection.userInterfaceStyle UIUserInterfaceStyleDark) { return [UIColor colorWithWhite:0.12 alpha:1.0]; } return [UIColor whiteColor]; }];struct ContentView: View { Environment(\.colorScheme) var colorScheme var body: some View { VStack { Text(标题) .foregroundColor(.primary) // 自定义颜色 RoundedRectangle(cornerRadius: 8) .fill(Color(AppBackgroundColor)) } } }场景现象排查思路导航栏颜色发灰使用了系统默认模糊效果检查prefersLargeTitles与 barTintColor 是否搭配合理图片背景变黑底图片本身透明像素在深色下露出背景检查图片来源、alpha通道文本看不清使用了固定前景色检查 UILabel.textColor 是否硬编码弹窗白闪控制器加载时背景色未设置提前设置 view.backgroundColor 或 tintColor第三方SDK页面不适配SDK 内部硬编码等待SDK升级或用overrideUserInterfaceStyle局部处理WebView 内容反白失败WebView 未设置contentMode .always设置webView.isOpaque false配合 CSS 校验状态栏文字不可见状态栏样式与背景色冲突设置preferredStatusBarStyle动态切换阴影在深色下消失阴影使用纯黑色且不透明度低改用带透明度的动态色或加描边以上是问题排查速查表在实际适配过程中你会遇到更多组合形态的怪问题。下面聊几个我印象深刻的坑。图片切割导致的横线某次适配后列表里几张图片在浅色模式正常深色模式下边缘出现一条亮线。原因是图片资源只有Any一份内部没有拉伸保护在深色下边缘像素被抗锯齿放大。解决方式是让设计重新导出带安全边距的图片或者我给图片包一层ImageView用代码裁掉边缘透明像素。单元格复用导致的颜色串台表格dequeueReusableCell里如果背景色放在cellForRow里设置切换主题后滑动列表会出现颜色闪烁因为复用池里的 Cell 还在用旧 trait。解决方式是在layoutSubviews或prepareForReuse里重新更新颜色别在数据回调里设置。系统控件在暗黑下的双重绘制状态栏、导航栏这类系统控件如果既用了barTintColor又用了动态色深色模式下会出现双重渲染颜色比预期更深。我后来统一走UINavigationBarAppearance设置backgroundEffect和backgroundColor避免混用。暗黑模式下的弹窗层级UIAlertController在默认配置下会自动适配但如果你的 App 整体是深色而系统是浅色弹窗会维持系统风格跟 App 不搭。这时只能自己定制一个弹窗视图别指望系统弹窗完全贴合你的设计。深色模式下UIBlurEffect的穿透问题如果模糊层后面是个纯白视图在深色模式下灰蒙蒙看起来像所有内容都被蒙了一层雾。解决方式是模糊层背后加一层和背景同色系的半透明视图或者直接用UIVibrancyEffect配合。深色模式下截图颜色不一致用户反馈截图分享后颜色偏灰。原因是我用了系统动态色但分享时做了位图渲染动态色解析成了浅色值。解决方式是在分享前手动转成目标色值或者强制以当前 trait 进行drawHierarchy。从浅色切深色时闪白进入设置页切换主题后返回主页有一段白底闪烁。原因是 rootViewController 的背景色更新时机晚于视图加载。我在切换主题后主动调用setNeedsLayout和layoutIfNeeded解决了。深色模式下图层混合模式异常某张半透明蒙层在深色下出现明显的锯齿和噪点因为蒙层颜色和底下图片颜色相近但混合模式不对。换成sourceOver或调整蒙层alpha值就好。其实这些坑说起来都小但每一个都费了不少时间定位。下面说说我怎么验证和收尾的。另外我还发现直接调试真机上的暗黑模式比模拟器靠谱模拟器某些渲染上的坑并不完全等同于真机尤其是导航栏和模糊层真机和模拟器的表现有明显差异。如果你手头有测试设备也别只测最新系统。Xcode 支持在模拟器里切换系统版本我一般会拿一个低版本系统和一个高版本系统分别跑一遍暗黑模式看有没有兼容性问题。虽然大部分代码是同一套但系统版本不同某些效果实现细节还是有差异。最后总结几条我自己跑过无数坑后的经验和心得希望能帮读者少走弯路。 - 首先适配前把设计规范定清楚别边写代码边等设计出图。 2. 优先使用系统语义色和 Assets 里的动态色少在代码里硬编码#FFFFFF、#000000。 3. 对所有UIColor的使用做一次审查包括第三方开源库里的色值。 4. 善用模拟器的暗黑模式一键切换功能但最终以真机结果为准。 5. 遇到奇怪的显示效果先排除颜色空间、混合模式、图片 alpha 通道等底层因素。 6. 多备份几套测试截图方便回归。这套流程我从最初的几个页面现在已经覆盖了整个 App前后大概花了两周多时间改动量其实不算大但收益很高——每次系统更新、用户反馈体验提升都是实打实的。适配暗黑模式的本质是把 App 从“固定皮肤”变成“能响应环境切换的界面体系”一旦这个架构搭起来以后新增页面或者调整设计风格成本都会低很多。对读者来说如果你们也在做 iOS 暗黑模式适配我建议先从最小的页面开始练手跑通全流程再逐步推广。代码层面不要过分依赖某个“一刀切”方案还是那句系统语义色 Assets 动态色 代码里有限的动态 Provider这样搭配下来既能保证兼容性又能照顾到特殊场景。也许有人觉得暗黑模式不是刚需但用户端的感知是很直观的。我在搞这个适配的过程中收到过不少用户主动发消息说“夜间模式太好用了”这比很多隐藏功能都更有存在感。如果后面有时间我还会再把图片加载这一块的暗黑适配再做一轮优化把网络图片的动态变色方案也落实下来。暂时先写到这里希望这篇实战笔记能帮到正在做同类适配的开发者。