Cocos Creator3.8.0 + Tiled1.4.x 地图加载FAQ（高频报错+秒解）

一、加载失败类（最常见）

1. 报错Unsupported TMX versio

✅ 解：Tiled版本过高，换1.4.x导出，或导出时勾选兼容1.4格式

2. 地图空白无显示，无报错

✅ 解：tmx/tsx/瓦片图不同目录；或资源没放resources文件夹，路径写错

3. 报错Cannot find tile set

✅ 解：tsx内嵌改外部引用；或拖入Cocos时漏传瓦片图/png

4. 编辑器拖tmx到组件无效

✅ 解：检查tmx文件导入设置，勾选可导入，重启编辑器重试

二、显示异常类

1. 瓦片错位、重叠、显示不全

✅ 解：Tiled里地图瓦片尺寸与Cocos节点适配一致；不使用高版本等距/六边形瓦片

2. 部分图层不显示

✅ 解：Tiled里图层未勾选"可见"；或图层名中文，改英文（如Ground/Obstacle）

3. 瓦片图模糊、失真

✅ 解：Cocos里瓦片图纹理设置为点采样，关闭抗锯齿

三、代码相关类

1. 代码写路径后地图不加载

✅ 解：路径不加.tmx后缀；资源放resources下，路径从resources开始写（例map/test）

2. getLayer获取图层返回null

✅ 解：图层名大小写不一致（Tiled和代码必须完全匹配）；排除地形层等高版本不支持图层

3. 动态创建节点后地图位置偏移

✅ 解：给mapNode设置锚点(0,0)，与Tiled地图原点对齐

四、格式兼容类

1. 二进制格式tmx加载失败

✅ 解：Tiled导出必选XML格式，禁用二进制/CSV格式

2. 高版本Tiled做的地图兼容报错

✅ 解：删除图层特效、自定义高级属性等1.5+新增功能，重新导出

3. tsx文件报错无法解析

✅ 解：Tiled里瓦片集导出为外部tsx，不选内嵌到tmx