Codex Dream Skin 没有效果怎么办？端口、Node.js 与启动问题排查

正文

Dream Skin 启动失败时，最容易犯的错误是反复重装或随意杀掉所有 Node 进程。更稳妥的方法是按层排查：运行环境、Codex 进程、CDP 端口、注入器和主题图片。

Node.js 版本不够

Windows 版要求 Node.js 22 或更高：

低于 22 时，从 Node.js 官网安装新的 LTS，并重新打开 PowerShell。macOS 通常使用 Codex 自带的签名 Node.js，但需要先启动官方 Codex 并生成 ~/.codex/config.toml。

node --version

Codex 已打开

Dream Skin 需要带 --remote-debugging-port 启动 Codex。如果已有普通实例运行，脚本会要求退出，避免未保存输入丢失。保存任务后完全退出，再运行启动脚本。

Windows 可明确授权重启：

只有确认没有重要未保存内容时才使用。

powershell -ExecutionPolicy Bypass -File .\windows\scripts\start-dream-skin.ps1 -RestartExisting

端口被占用

Windows 默认首选 9335，macOS 默认从 9341 开始。未手动指定端口时会寻找空闲端口；显式指定的端口被占用则失败关闭。不要把端口映射到公网，也不要关闭不认识的监听程序。

Windows 换端口：

macOS：

powershell -ExecutionPolicy Bypass -File .\windows\scripts\start-dream-skin.ps1 -Port 9450

./scripts/start-dream-skin-macos.sh --port 9450

有背景但按钮点不了

通常是导入了带 UI 的截图，或装饰层版本过旧。Restore 后重新导入纯背景图：不能有窗口、侧栏、按钮、输入框、Logo、文字和水印。正常装饰层应不接收鼠标事件，真实控件位于上层。

图片导入失败

Windows 会拒绝超过 16 MB、单边超过 16384 像素或总像素超过 50MP 的图片；macOS 主定制入口可接收更大的源图，但最终主题仍受 16 MB 限制。先导出为 2560×1440 JPEG，再重新导入通常最省事。

更新后身份不匹配

项目会检查 Store 包身份、可执行文件、浏览器 ID 和 renderer 标记。Codex 更新后旧状态可能不再对应当前版本。完全退出 Codex，更新 Dream Skin，重新运行 install/start，让脚本发现当前应用。不要手动修改 state JSON。

日志在哪里

Windows：%LOCALAPPDATA%\CodexDreamSkin，重点看 injector.log、injector-error.log、verify.log 和 state.json。macOS：~/Library/Application Support/CodexDreamSkinStudio。提交日志前删除用户名、项目路径、任务内容和密钥。

什么时候直接恢复

出现以下情况，先 Restore：

恢复脚本会优先验证身份，无法安全确认时保留状态并停止，不会盲目关闭未知程序。

Codex 反复崩溃或无法打开。
Verify 无法确认端口属于 Codex。
状态文件记录的进程已经不存在。
主题层遮挡输入框或复制按钮。
你不确定某个 Node 进程是不是 Dream Skin。

常见问题

这篇教程适合直接照做吗？

可以作为操作参考，但执行命令前应先确认来源、平台路径、当前 Codex 版本和恢复方式。

如果换肤后界面异常，先做什么？

先停止当前自定义会话并运行 Restore，不要继续叠加新主题或手工删除配置。

正文