Cocos MCP Pro Troubleshooting

Version: 0.2.0

先运行“一键检测”

面板会分别检查Node、Bridge、WebSocket、Creator Scene和客户端配置。先处理第一个失败项，不要连续重装或盲目重试写操作。

面板打不开或提示`methods`不存在

确认正式ZIP的根目录直接包含package.json、dist/main.js、dist/scene.js和dist/panels/default/index.js，没有多嵌一层扩展目录。移除不完整或旧版扩展后重新导入正式ZIP，并重启Creator。不要把未构建源码目录当作商店扩展安装。

Creator 3.8.8在Windows上若提示unzip: No zipfiles found后又报ENOENT scandir，先把ZIP复制到只含英文和数字的本地路径（例如C:\CocosMCP\cocos-mcp.zip）再导入。这个报错可能来自Creator内置解压器无法读取ZIP来源路径中的中文；项目目录本身仍可保留中文、空格和&。

客户端提示`Connection closed`

保持Creator和当前工程打开，确认面板服务正在运行。
在面板里重新配置对应客户端。v0.2.0会迁移旧的.cocos-mcp-launcher.cmd或.sh配置。
完全退出并重启AI客户端，然后调用cocos_ping。
若仍失败，运行“一键检测”并查看客户端MCP日志。

正确配置应直接执行Node，参数依次包含bridge-cli.js、--project和工程目录。不要手抄他人的绝对路径。

提示`bridge cli missing`或路径乱码

这通常是旧版启动器或扩展目录不完整。卸载旧扩展，重新导入完整v0.2.0目录，再执行一键配置。路径中包含中文、空格或&时，不需要额外加转义字符；让面板生成配置即可。

提示`node not found`

安装Node.js 18至24，再回到面板重新运行一键配置。v0.2.0会把实际Node可执行文件的绝对路径写入客户端配置，不依赖GUI应用的PATH。

配置文件原有内容丢失了吗

不会直接覆盖。插件会解析现有JSON/TOML，更新cocos-creator条目，写入临时文件并校验后原子替换。原文件存在时会保留同目录.cocos-mcp.bak备份；格式损坏时会停止并明确报错。

MCP连上了，但简单UI任务仍要求手动挂脚本

先调用cocos_get_capabilities，确认版本为0.2.0。圆形、矩形、文本、图片和按钮应使用cocos_create_ui_*或cocos_apply_ui_spec，不应临时生成组件脚本让用户手动挂载。若客户端仍这样规划，把这句话补给它：

使用Cocos MCP Pro任务级UI工具直接完成；失败时返回诊断并回滚，不生成临时脚本，不要求我手动操作Creator。

UI任务失败后留下半成品

停止继续写入，立即保存diagnostics并提交问题。cocos_apply_ui_spec设计为事务操作，任一步失败都应自动移除本次创建的节点。不要在残留状态上继续让AI“补救”。

图片或字体资源写入失败

set_component_property可接受资源UUID，也可直接接受assets/...路径。路径必须存在且资源类型与目标属性匹配；插件会在写入前解析并校验，不匹配时拒绝修改。

网页报错怎么读

使用cocos_preview_debug_start打开托管Chrome/Edge预览，不要把普通浏览器页面来回复制给AI。复现后调用cocos_preview_debug_read；可读取JavaScript异常、未处理Promise、控制台错误和失败网络请求。结束时调用cocos_preview_debug_stop。

Android或iOS构建是否一定不受影响

不能只凭编辑器或网页错误下结论。cocos_get_build_diagnostics只整理Creator已有构建日志；仍需实际完成目标平台构建和设备测试。

反馈问题

邮箱：jimmymjing@gmail.com

请附Creator版本、插件版本、系统、AI客户端、一键检测结果、复现步骤和脱敏诊断。不要发送项目密钥、API Key或完整商业项目。

3.8 KiB Executable File Raw Blame History