troubleshooting.md

问题排查

返回文档目录

应用了 ICC，但颜色完全没有变化

按顺序检查：

1. 在 DisplayTune 中确认 ColorSync 回读的当前 ICC 与所选文件一致。
2. 点击“测试色彩通道”，观察屏幕是否短暂偏红并自动恢复。
3. 关闭 HDR、Night Shift、True Tone 和第三方护眼工具。
4. 用受 ColorSync 管理的普通 macOS 应用比较，不要先用游戏、视频播放器或远程桌面判断。
5. 退出可能持续改写 Gamma/LUT 的软件。
6. 注销并重新登录，再重新选择 ICC。

如果“测试色彩通道”也没有变化，当前显示链路可能未暴露可写 GPU LUT，或系统/应用正在 覆盖它。软件视觉匹配在这种链路上无法正常工作。

颜色变化了，但仍不像 Mac 内建屏

• 确认两块屏幕使用相同目标：sRGB 对 sRGB，或 Display P3 对 Display P3。
• 不要把显示器 OSD 的 DCI-P3 直接等同于 Apple Display P3。
• 固定两块屏幕亮度后再比较白点。
• 先匹配白色和中灰，不要先比较高饱和图片。
• 检查外接显示器是否只有 sRGB 级色域；软件无法生成面板没有的 P3 原色。
• 对准确性有要求时使用实体校色仪。

自动寻色或视觉调节按钮没有反应

1. 先在主界面选择 Mac Match、sRGB Target 或 Apple Display P3 这类可写入视觉曲线的 独立 ICC。
2. 确认主界面的 LUT 状态不是“该显示链路未暴露 GPU LUT”。
3. 关闭 HDR 和会覆盖 Gamma 的应用。
4. 点击色彩通道测试；如果回读失败，自动寻色会停止且不会保存。
5. 取消当前视觉会话后重新打开校色窗口。

找不到“自动寻色 / 校色仪…”

主菜单中有独立的“自动寻色”卡片，色彩设置区域也有“自动寻色 / 校色仪…”按钮。窗口 可能已经在其他 Space 或显示器上打开，可使用 Dock/调度中心查找。

校色仪显示未安装

“校色仪”指实体 USB 光学硬件，不是纯软件模拟。

brew install argyll-cms
which dispcal
which spotread

安装后关闭并重新打开校色窗口，点击重新检测。还需要：

• 连接受 ArgyllCMS 支持的校色仪；
• 允许终端/应用访问相关 USB 设备；
• 退出厂商自带的、可能独占仪器的软件；
• 确认 ArgyllCMS 能在终端中列出显示器和仪器。

DDC/CI 不可用

• 在显示器 OSD 中开启 DDC/CI。
• 直接连接显示器，移除扩展坞/KVM/转接器后测试。
• 更换输入和线材。
• 关闭 PBP/PIP。
• 睡眠唤醒后重新探测或重新插拔。
• 检查 DDC 映射状态，而不只看“显示器未响应”。

单项不支持是正常情况。例如亮度可读但 RGB Gain 不可读时，DisplayTune 只启用亮度。

多显示器映射不明确

DisplayTune 为避免控制错屏会禁止写入。可以：

1. 暂时只连接一台外接显示器并重新探测。
2. 让每台显示器使用不同输入或直接连接。
3. 关闭虚拟显示器、DisplayLink 或屏幕录制虚拟输出。
4. 提交包含 VID/PID 和连接链路的兼容性报告。

不要通过修改代码强制按数组顺序匹配；系统服务枚举顺序不保证稳定。

分辨率切换后黑屏

等待 15 秒，应用会尝试恢复原模式。不要在倒计时期间拔掉目标显示器。

如果没有恢复：

1. 重新连接显示器。
2. 使用 macOS“系统设置 → 显示器”选择安全模式。
3. 按住 Option 查看更多分辨率。
4. 注销或重启，使 session 级显示配置被重建。

提交问题时请写明原模式、目标模式、刷新率、HiDPI 和连接方式。

登录时启动不可用

• swift run DisplayTune 不是 .app，无法注册主应用登录项。
• 先运行 ./scripts/build-app.sh，再把应用复制到 /Applications。
• 在系统设置的登录项页面批准。
• 移动或重命名应用后，先关闭登录启动，再从新位置重新开启。

日夜定时没有切换

• 确认开关已启用。
• 检查日间与夜间开始时间不相同。
• 系统睡眠期间不会执行界面更新；唤醒后等待下一次时间检查。
• DDC 亮度不可用时只会使用软件路径，视觉效果可能较弱。
• Night Shift 若同时启用，会与夜间色温叠加。

恢复原厂 ICC 和颜色

1. 点击“恢复系统色彩”。
2. 关闭日夜定时和连接时自动恢复，避免旧配置再次应用。
3. 在“系统设置 → 显示器 → 颜色描述文件”确认默认描述文件。
4. 必要时退出 DisplayTune 并注销。

生成的 ICC 位于 ~/Library/ColorSync/Profiles/。只有确认不再使用时才删除以 DisplayTune 开头的文件。

如何收集报告

请优先复制文字状态，而不是上传完整桌面截图。需要包含：

• DisplayTune 版本和构建号；
• Mac 型号/芯片、macOS 版本；
• 显示器、输入、固件、扩展坞和线材；
• VID/PID、分辨率、刷新率、HiDPI；
• DDC 映射与五项 VCP 状态；
• 当前 OSD 模式、HDR/Night Shift/True Tone 状态；
• 可复现步骤和预期结果。