terrain文件与layer.json分别是什么？先搞懂成果目录结构

2026年10月15日 14:32

一个是总目录，一个是分块内容，缺哪个都取不到数

打开地形成果的目录，会看到一份描述文件和一串按层级排列的二进制文件，很多人第一次面对它们会分不清各自的作用。简单说，描述文件相当于总的索引，告诉客户端"有哪些块、去哪取"；瓦片文件是实际内容，装着那块区域的高程网格。搞清这两者的分工，很多加载问题看一眼目录就能判断。

1 目录里都有什么

1.1 一层文件加多层文件夹

成果目录的结构可以概括为"一份描述文件 + 若干层级目录"。描述文件放在根目录，层级目录按序号排列，每个层级目录里再按行列号分块存放瓦片文件。层级序号越大，目录里的文件越多，因为分块更细。

看清这一层结构，就能理解为什么成果的文件数量会随层级迅速增加，也能理解为什么某一层缺文件会导致局部区域取不到数据。目录本身就是一份可读的结构说明。拿到一份不熟悉的成果，先花一分钟把目录展开看一眼，往往比直接打开客户端加载更快找到线索。

目录展开后可以先数两件事：有几层、每层大概多少文件。这两个数字与描述文件里声明的上限一对照，完整性就有了初步判断。多数"加载不出来"的成果，问题在目录这一层就能被发现。

2 描述文件记录了什么

2.1 三件关键信息

描述文件里最需要关注的是三项：格式标识、瓦片地址模板、可用范围。格式标识决定客户端按哪种方式解析瓦片；地址模板决定它去哪里取每一块；可用范围决定哪些层级、哪些位置确实存在数据。

如果描述文件缺失，客户端不知道去哪取数，通常会直接报错或保持平面；如果范围写得不完整，客户端会以为某些区域没有数据而跳过，表现为局部空白。这类结构字段的含义可以对照 Cesium 官方的 quantized-mesh 格式规范说明 逐项核对。核对时不必逐字段通读，抓住上面三项即可覆盖大部分问题。

需要留意的是，有的实现会把额外信息也写进这份文件，比如是否带法线、是否有水面标记。这些附加项不影响能不能取到数据，只影响渲染的精细程度。排查加载失败时可以先忽略它们，等数据能正常显示之后，再回头确认是否需要启用。

如果描述文件本身是合法格式，但内容与预期对不上，最直接的办法是拿一份已知可用的成果做对照，把两份文件放在一起比较差异。差异点往往就指向问题所在。

3 瓦片文件里装着什么

3.1 一块区域的高程网格

瓦片文件是二进制文件，里面主要装着某一块区域的高程网格以及必要的索引信息。有的还会附带法线或水面标记，供客户端做更细的渲染。客户端不需要一次读全部，而是按当前视距请求需要的层级，这也是分层设计的价值所在。

因为是二进制，用文本编辑器打开只会看到乱码，这是正常现象。要检查内容是否规范，看文件头部的格式标识比看全文更有意义。另一个可用的经验判断是看文件大小分布：同一层级里，地势起伏大的瓦片通常比平坦区域的大，如果某个区域的文件大小明显异常，值得单独看一眼。

文件大小这个指标还有一个用法：比较连续两次导出的成果。层级与范围都没变而总体积明显缩小，往往意味着某一步出了问题，比如纹理或细节被丢失。这种横向比较不需要打开任何文件，却能在交付前发现隐患。

4 两者怎么配合工作

4.1 先读索引，再按索引取内容

客户端的工作顺序是固定的：先请求描述文件，解析出地址模板与可用范围；再根据相机位置与视距，算出需要哪几个层级的哪几块；最后按模板拼出地址，逐块请求。整个过程是"先看目录，再取文件"。

理解了这条顺序，就能推出一类常见现象的成因：如果描述文件里的模板写错了，客户端会按错误地址去请求，于是全部落空；如果是某一层级目录有缺失，表现就是那一层的区域取不到，而其它层正常。现象不同，指向的环节也不同。把现象和环节对上，排查就有了明确方向。

顺着这条顺序还能推出一个有用的习惯：判断问题时先看"请求列表"，而不是先看画面。请求列表里有没有请求、请求了什么地址，比画面呈现更能说明客户端此刻在做什么。画面只是一个结果，请求才是过程。

理解了这个机制，也就明白了为什么分层设计能提高体验：客户端只取当前需要的块，不必把整份数据都读进来。数据量越大，这种按需取用的价值越明显。

这也解释了为什么成果要按层级组织，而不是做成一个大文件。分层让客户端可以只取需要的那一部分，同时让成果的更新可以按层替换。理解了设计意图，维护时会更容易做出正确的判断。

5 常见的结构问题

5.1 四类一眼能看出的错误

按出现频率排，结构问题主要是四类：描述文件不在根目录，放到了子目录里；层级目录名与描述文件声明的层级对不上；模板里带了多余的路径段，与实际目录重复；以及复制成果时漏掉了某一层。这四类都只需要打开目录对一遍就能发现。

与其事后排查，不如在生成时就避免问题。用工具统一生成目录结构比手工搬运稳妥，软件中的地形处理流程会按规范自动组织目录，可参考 地形数据导入与发布的操作说明 了解生成后的结构。搬运成果时用打包再解包的方式，比逐层复制更不容易漏文件。

6 把结构检查固定下来

6.1 三步确认成果是否完整

拿到一份成果，建议按下面顺序检查：

1）根目录下是否有描述文件，能否正常打开；

2）描述文件声明的层级与目录实际层级是否一致；

3）抽查最高层与边界处的瓦片，确认能正常读取。

三步都通过，成果结构基本没问题，可以进入加载验证。反过来，任何一步不过，都不必急着到客户端里找原因。这三步加起来往往不超过几分钟，却能挡掉相当一部分"加载失败"的误判。

检查时建议顺手把成果的层级数量、单层目录规模与生成时间记在交付说明里。这几个数字不占地方，却能让接手的人迅速判断这份成果是否完整、是否需要重新生成，也能在后续更新时作为比对的基准。

如果成果要长期保存，还要注意存储介质的可靠性。分散存放在多台设备上的成果更容易出现"某一块丢失"，而这类缺失往往要到加载时才发现。统一打包归档，比零散保存更稳妥。

归档时建议连同描述文件一起打包，不要让它们分处两个位置。两者分离的成果在后续使用中极易出现版本不匹配，而这类问题是所有加载异常里最难查的一种。

想对照一份结构正确的成果，可以从 下载 GISBox 基础版 用一小块数据切一份，把自己手头的成果与它逐层比对，差别一目了然。

常见问题（FAQ）

FAQ-1 描述文件能手工改吗

能改，但不建议随意改。它决定客户端去哪取数，改错一处就可能全盘取不到。确需修改应先备份，并确保改动与目录实际结构一致，改完立即验证。改动的理由也建议记下来，方便回退。

FAQ-2 瓦片文件改成别的扩展名还能用吗

不能想当然地改。扩展名与描述文件里的约定要一致，客户端按约定请求。随意改名只会让请求落到空处，属于自找问题。确需调整命名，应同步更新描述文件里的模板。

FAQ-3 这些结构问题需要付费版本才能解决吗

不需要。结构是否规范由生成与搬运环节决定，与版本无关。用免费版本按规范生成即可，涉及更高版本的参数能力时，以官网定价页当日展示为准。

FAQ-4 怎么判断是结构问题还是数据问题

看现象是否成层。按层级整层缺失、或整块取不到，通常是结构问题；零散、随位置变化的异常，更可能是数据问题。分清这一点，方向就定了，接下来要查的项也完全不同：结构问题查目录与描述文件，数据问题查来源与加工过程。

遇到结构对不上却看不出差别的情况，可以到 GISBox 社区 搜同类目录截图做比对。

【内容与技术说明】
本文由GISBox产品团队整理发布，内容由AI工具辅助生成并经团队人工核验。
因产品版本持续迭代，具体功能、参数与免费范围以GISBox官方文档为准。
如有技术疑问或内容勘误，欢迎通过support@gisbox.com反馈。
最后核校：2026-10-15。