在 Safari 里打开一个 Three.js 演示页，满心期待流畅的 3D 场景，结果却卡成 PPT、模型渲染成一团空白，帧率连 30fps 都稳不住？更糟的是，打开控制台，赫然报错 "WebGL not available"。

遇到这种情况，先别急着怀疑自己的代码。大概率不是网页本身的事，而是 Safari 的 GPU 加速通道压根没被正确激活。系统正被迫用 CPU 做软件渲染，硬件没使上劲儿。

解决起来其实不复杂。跟着下面四个步骤，基本能搞定。

步骤一：启用开发菜单并校验 WebGL 基础状态

所有后续操作的前提，就是让 Safari 的“开发”菜单现身。Safari 不像其他浏览器那样有图形化的 WebGL 开关，一切控制都得从这里开始。

1. 显示开发菜单

• 打开 Safari → 顶部菜单栏点击 Safari → 偏好设置 → 切换到“高级”标签页
• 勾选【在菜单栏中显示“开发”菜单】

2. 检查 WebGL 停用状态

• 关闭偏好设置窗口，在顶部菜单栏找到新出现的“开发”菜单
• 检查子项中“停用 WebGL”是否已被勾选
• 【若已勾选，必须立即点击取消，否则后续所有操作均无效】

3. 确认 GPU 启用状态

• 继续在“开发”菜单中选择“图形处理器信息”
• 确认弹出窗口里列出的是真实 GPU 型号（如 Apple M3 Pro、AMD Radeon Pro 5500M 或 Intel Iris Xe），而非 "Software Renderer" 字样
• 若显示后者，说明系统级 GPU 加速已被完全绕过，第一步已经失败

步骤二：关闭系统级干扰策略，释放 Metal 渲染路径

macOS 系统的很多设置，比如辅助功能、电池策略或显示器配置，都会在后台动态压制 GPU 的能力。这些系统级开关的优先级比 Safari 自身配置还要高。

① 显示器设置

• 点击苹果图标 → 系统设置 → 显示器 → 高级
• 确保开启“使用图形处理器进行窗口管理”

② 辅助功能设置

• 返回系统设置 → 辅助功能 → 显示
• 关闭“降低透明度”和“减少动态效果”
• 这两项一旦开启，会直接禁用 Metal 合成器，WebGL 立马降级为 CPU 渲染，帧率自然惨不忍睹。

③ 电池策略设置

• 进入系统设置 → 电池 → 电源适配器
• 关闭“优化视频流播放以延长电池寿命”
• 这个选项会在后台持续限制 GPU 频率，让 WebGL 无法稳定在 60fps 运行。

步骤三：通过终端写入底层偏好键，强制启用 WebGL 2.0 与 Metal 渲染

光靠界面操作是唤不醒 Safari 的实验性 Metal 后端的。必须通过终端直接注入 WebKit 的底层开关。

方法一：启用 WebGL 基础支持与硬件合成

• 打开“应用程序” → “实用工具” → “终端”
• 依次执行以下三条命令（每输完一条按回车）：

defaults write com.apple.Safari WebKitWebGLEnabled -bool true
defaults write com.apple.Safari WebKitWebGL2Enabled -bool true
defaults write com.apple.Safari WebKitUsesHardwareAccelerationForCompositingOnDesktop -bool true

方法二：解锁 Metal 渲染开关（macOS 14+ 必做）

• 在终端中继续输入：defaults write com.apple.Safari IncludeInternalDebugMenu -bool true
• 重启 Safari → 顶部菜单栏将出现“调试”菜单
• 点击“调试” → 查找 "Use Metal for WebGL" 选项 → 确保其已勾选启用

步骤四：清除损坏缓存与网站数据，重置 WebGL 上下文

长期运行积累的异常 WebGL 上下文、损坏的着色器缓存，或是冲突的网站策略，都可能导致 GPU 初始化失败后永久地回退到软件模式。需要动手清理一波。

1. 清除历史记录

• Safari 菜单 → 清除历史记录与网站数据 → 选择“所有历史记录” → 点击“清除历史记录”

2. 移除特定网站数据

• 偏好设置 → 隐私 → 管理网站数据 → 按“大小”排序
• 找到 threejs.org、babylonjs.com、webglsamples.org 这些 WebGL 密集型站点
• 选中它们 → 点击“移除”

3. 清理缓存文件

• 在终端中执行：rm -rf ~/Library/Caches/com.apple.Safari/WebKit*

4. 完全重启 Safari

• 按 Command + Q 完全退出 Safari
• 等进程彻底消失后再重新启动

至此，四步操作全部完成。大多数情况下，Safari 的 WebGL 就能恢复正常，硬件加速重新上岗。你那些 3D 场景也终于能跑出该有的流畅度了。