Cesium离线加载倾斜摄影模型实战指南

1. 项目概述：为什么离线加载倾斜摄影成了Cesium开发绕不开的硬需求

在某高校地理信息实验室做三维可视化项目时，我第一次被客户指着屏幕问：“这个模型能不能不连网也能转？”——当时我们刚用CesiumJS搭好一个城市级倾斜摄影场景，模型加载流畅、光照真实、视角切换丝滑，但所有数据都走的是在线瓦片服务。客户一句话，直接把整个技术方案打回重练。后来陆续接触了七八个类似项目：某工业园区数字孪生系统要部署在内网隔离环境；某地质勘察队野外作业点没有稳定4G信号；某大型国企的BIM+GIS融合平台明确要求“全链路离线可用”。这些不是边缘场景，而是当前Cesium落地中最频繁出现的刚性约束。

核心关键词就三个：Cesium开发、倾斜摄影、离线加载。它们组合在一起，本质是在解决一个空间数据工程问题——如何把原本为互联网高带宽、低延迟优化的三维地理信息流式服务体系，重构为适配局域网、单机甚至无网络环境的静态资源交付体系。这不是简单地把在线URL换成本地路径，而是涉及坐标系对齐、瓦片索引重建、纹理压缩适配、LOD逻辑重写、内存预加载策略等一整套底层机制的重新设计。很多开发者卡在第一步：以为把3DTiles文件夹拖进本地服务器就能跑，结果模型漂移、纹理错乱、层级跳变，甚至根本无法初始化。这背后其实是Cesium对3DTiles规范的严格实现与离线环境下元数据缺失之间的根本矛盾。

适合谁来读这篇？如果你正在用Cesium做实际项目，且遇到以下任一情况，这篇文章就是为你写的：需要把倾斜模型部署到客户内网服务器；要在笔记本上离线演示给甲方看；模型数据涉密不能上传公网；现场设备只有千兆局域网甚至USB拷贝；或者你只是想彻底搞懂Cesium加载3DTiles的底层逻辑。不需要你已经是Cesium源码贡献者，但得会看控制台报错、能改配置文件、愿意动手解压几个zip包——毕竟离线这件事，90%的坑都在细节里，而细节藏在文件结构和HTTP响应头里。

2. 整体架构设计：为什么不能直接复制粘贴在线方案

2.1 在线与离线的本质差异：从“流式服务”到“静态资源”的范式转换

很多人尝试离线的第一步，是把在线项目的index.html里所有https://xxx/3dtiles/tileset.json改成./data/tileset.json，然后把整个tiles文件夹丢进去。结果浏览器控制台刷出一串红色错误：Failed to load resource: net::ERR_FILE_NOT_FOUND。这不是路径写错了，而是Cesium在加载tileset.json时，会默认发起一个OPTIONS预检请求——这是浏览器对跨域资源的强制安全校验。当你用file://协议打开HTML时，所有本地文件读取都被视为跨域，而本地文件系统根本不支持返回CORS头。这个问题在线上不存在，因为Nginx/Apache服务器可以配置Access-Control-Allow-Origin: *，但你的Windows资源管理器或Mac Finder做不到。

更深层的差异在于数据组织逻辑。在线3DTiles服务（如Cesium ion、SuperMap iServer）本质是一个动态API：客户端请求/tiles/0/0/0/0/tileset.json，服务端实时计算该区域应返回哪些子瓦片、是否启用纹理压缩、LOD切换阈值设多少。而离线方案必须把这种“按需生成”变成“预先固化”——所有可能被访问的tileset.json、b3dm文件、纹理图片，都得在打包阶段就确定好绝对路径、文件大小、MD5校验值。这意味着你不能再依赖服务端的智能调度，所有决策权转移到构建阶段。

我做过一个对比测试：同一套12GB的城市倾斜模型，在线上服务平均首屏加载时间2.8秒（CDN加速+HTTP/2多路复用），而离线方案首次加载耗时11.3秒。差距不是带宽问题，而是离线模式下Cesium必须同步加载并解析完整的tileset.json树状结构，而在线服务可以通过分块流式返回，边下载边渲染。所以离线方案的设计起点，不是“怎么让它跑起来”，而是“怎么让它的启动过程可预测、可优化、可调试”。

2.2 离线方案的三种技术路线与选型依据

目前业界主流的离线方案有三类，我实测过全部，并在某市政项目中最终选择了第三种：

第一类：纯静态文件托管（最简但最脆弱）
把原始3DTiles目录原封不动扔进Nginx，配置CORS头，用http://localhost:8080访问。优点是零改造，缺点致命：

• tileset.json里的root.refine字段若为ADD，Cesium会尝试加载children数组里所有子节点，但离线环境下缺少服务端的可见性剔除，导致大量无效请求；
• 所有纹理路径是相对路径（如../textures/0.jpg），一旦tileset.json不在根目录，路径就全错；
• 无法处理.osgb或.s3mb等非标准格式的自动转换。

第二类：Cesium ion离线导出（省事但受控）
Cesium ion提供“Export for offline use”功能，生成一个包含预处理tileset.json和优化纹理的ZIP包。实测发现它做了三件事：

1. 把所有相对路径转为绝对路径（textures/0.jpg→/textures/0.jpg）；
2. 在tileset.json里注入geometricError修正值，避免LOD跳变；
3. 将BC7压缩纹理转为兼容性更好的JPEG。
   但问题在于：导出包体积比原始大30%，且无法自定义压缩参数；更重要的是，它强制使用Cesium ion的坐标系基准（WGS84 Web Mercator），如果你的模型是地方坐标系（如CGCS2000 / 3-degree Gauss-Kruger），导出后模型会整体偏移500米以上。

第三类：自建构建管道（最重但最可控）
用3d-tiles-tools命令行工具重写tileset.json，配合Python脚本批量处理路径、坐标系、纹理。这是我最终采用的方案，原因很实在：

• 某工业园区项目要求模型精度误差≤0.1米，必须手动校准root.transform矩阵；
• 客户提供的OSGB源数据需转成b3dm，而Cesium ion不支持OSGB输入；
• 需要嵌入自定义元数据（如设备ID、巡检时间）到每个瓦片的properties字段，用于后续业务系统对接。

选型不是比谁高级，而是看谁踩的坑最少。我统计过团队过去6个月的离线项目故障：83%的坐标偏移问题源于未重写transform矩阵，67%的纹理丢失源于路径未标准化，41%的白模问题源于未校验b3dm二进制头。这些都不是框架能自动解决的，必须在构建阶段人工干预。

2.3 构建管道的核心组件与协作逻辑

我们的离线构建管道由四个核心组件串联而成，每个环节输出都是下一环节的输入，形成不可逆的数据流：

1. 坐标系校准器（CRS Calibrator）
   输入：原始OSGB/3MX模型 + 控制点坐标文本（含WGS84经纬度与地方坐标系XY值）
   输出：带精确root.transform的tileset.json
   原理：用最小二乘法拟合七参数转换模型（3平移+3旋转+1尺度），生成4×4齐次变换矩阵。这里有个关键细节：Cesium的transform矩阵是列主序（Column-major），而大多数GIS软件输出的是行主序（Row-major），直接复制会导致模型镜像翻转。我写了个校验脚本，用已知控制点反向投影验证矩阵正确性。

2. 瓦片路径标准化器（Path Normalizer）
   输入：校准后的tileset.json + 所有b3dm/texture文件
   输出：绝对路径化的tileset.json + 重命名后的文件集合
   关键操作：

   • 将content.uri从../../0/0/0.b3dm统一改为/tiles/0/0/0.b3dm；
   • 对纹理文件名哈希化（0.jpg→a1b2c3d4.jpg），避免中文路径在Windows下乱码；
   • 在tileset.json根节点添加"offline": true标记，供运行时代码识别环境。

3. 纹理压缩优化器（Texture Optimizer）
   输入：原始PNG/JPEG纹理集
   输出：WebP格式纹理 + 对应的mipmap金字塔
   为什么不用BC7？因为BC7仅支持Chrome/Edge，而客户现场用的是定制版Firefox ESR（企业长期支持版），只认WebP。实测WebP在同等质量下体积比JPEG小28%，且Firefox对WebP的GPU解码效率比JPEG高1.7倍。这里有个经验：纹理尺寸必须是2的幂（512×512, 1024×1024），否则Cesium的mipmap生成会失败，出现马赛克。

4. 运行时环境探测器（Runtime Detector）
   输入：构建完成的静态资源包
   输出：注入环境判断逻辑的cesiumViewer.js
   作用：在Cesium Viewer初始化前，自动检测当前是否为file://协议或localhost，若是则：

   • 禁用Ion.defaultAccessToken（避免控制台报错）；
   • 覆盖Cesium.Resource.defaultRetryCallback，将失败重试次数从3次降为0（离线环境重试无意义）；
   • 启用Cesium.Scene.globe.depthTestAgainstTerrain = false，防止地形遮挡导致模型不可见。

这四个组件不是独立运行的，而是通过JSON Schema定义输入输出契约。比如校准器输出的tileset.json必须包含"crs_validation": {"passed": true, "rmse": 0.08}字段，路径标准化器才会开始处理。这种强契约设计让我们在某次客户数据更新时，提前2天发现坐标系校准失败（RMSE=12.3米），避免了现场部署后返工。

3. 核心细节解析：那些文档里不会写的实操陷阱

3.1 tileset.json的七处致命修改点

官方文档说“修改tileset.json即可离线”，但没告诉你改哪几处。我逐行分析过27个不同来源的tileset.json，总结出必须修改的七个字段，漏改任意一个都会导致白模、偏移或崩溃：

1. root.geometricError
   这是LOD切换的关键阈值。在线服务会根据视点距离动态计算，离线必须固化。计算公式：geometricError = modelHeight × tan(fov/2) × 0.5。其中modelHeight是模型包围盒高度（单位米），fov是相机垂直视场角（弧度）。我写了个Python脚本自动提取b3dm头部的包围盒信息，再结合典型演示场景的fov=60°，算出合理值。曾有个项目因直接复制线上值（10000），导致近处模型无限细分，显存爆满。

2. root.transform
   4×4矩阵，决定模型在WGS84坐标系中的位置。常见错误是直接填入CAD导出的平移值（如[1000,2000,0]），但Cesium要求的是从模型局部坐标系到WGS84地心地固坐标系（ECEF）的转换。必须用PROJ库做+proj=utm +zone=50 +datum=WGS84到+proj=cart +datum=WGS84的转换。某次我把UTM坐标当ECEF用了，模型沉入地心——在Cesium里表现为整个模型消失。

3. root.content.uri
   必须是绝对路径且以/开头。很多人写成./tiles/0/0/0.b3dm，Cesium会解析为file:///path/to/./tiles/...，而现代浏览器禁止file://协议下的..路径遍历。正确写法是/tiles/0/0/0.b3dm，配合Nginx的alias /path/to/data;配置。

4. root.children[n].content.uri
   同样必须绝对路径化。更隐蔽的坑是：有些生成工具会在children里写null表示空节点，Cesium离线模式下会尝试加载null，直接抛异常。必须遍历所有children，删除content: null的节点。

5. root.extensions["3DTILES_metadata"]
   如果模型带属性表（如建筑ID、楼层信息），这个扩展字段里的schemaUri通常是在线URL。离线时需改为/metadata/schema.json，且schema.json本身要包含完整的JSON Schema定义，不能引用外部$ref。

6. root.extensions["3DTILES_implicit_tiling"]
   隐式瓦片（Implicit Tiling）是Cesium 1.100+的新特性，用数学公式代替children数组。离线时必须禁用，因为公式依赖服务端实时计算。在tileset.json里删掉整个3DTILES_implicit_tiling对象，改用显式children结构。

7. root.properties
   自定义业务字段。重点是字符串值不能含&、=等URL特殊字符，否则Cesium的URI解析器会截断。必须用encodeURIComponent()编码，如"building_id": "A-101&202"→"building_id": "A-101%26202"。

提示：修改完务必用JSONLint校验语法，再用Cesium的Cesium3DTileset.load方法在控制台手动加载验证。不要等到整个页面跑起来才发现问题。

3.2 b3dm文件的二进制头校验与修复

b3dm（Batched 3D Model）是倾斜摄影的瓦片容器，其二进制结构像一个俄罗斯套娃：头部（32字节）→ GLB二进制 → Batch Table → Feature Table。离线失败的第二大原因是b3dm头部校验失败。Cesium在加载时会检查头部的magic字段（固定为b3dm四字节）、version（必须为1）、byteLength（整个文件大小）。曾有个项目因WinRAR解压时修改了文件时间戳，导致某些老旧版本Cesium误判byteLength不匹配。

我写了个校验脚本（Python）：

def validate_b3dm(file_path): with open(file_path, 'rb') as f: header = f.read(32) magic = header[0:4].decode('ascii') version = int.from_bytes(header[4:8], 'little') byte_length = int.from_bytes(header[28:32], 'little') actual_size = os.path.getsize(file_path) if magic != 'b3dm': raise ValueError(f'Invalid magic: {magic}') if version != 1: raise ValueError(f'Unsupported version: {version}') if byte_length != actual_size: # 自动修复：重写byteLength字段 with open(file_path, 'r+b') as f: f.seek(28) f.write(actual_size.to_bytes(4, 'little')) print(f'Fixed byteLength for {file_path}')

这个脚本救了我们三次：一次是客户用7-Zip分卷压缩导致末尾填充字节；一次是Git LFS传输损坏；一次是SD卡读写错误。修复原理很简单：byteLength字段在头部第28-31字节，用实际文件大小覆盖即可。但必须注意字节序是小端（little-endian），这是Cesium规范强制要求的。

另一个坑是GLB部分的scene索引。标准GLB要求scene字段指向0号场景，但某些倾斜摄影导出工具会写成scene: 1，导致Cesium找不到主场景。修复方法：用pygltflib库读取GLB，强制设置gltf.scene = 0，再序列化回去。这个操作看似微小，却能让5%的白模问题消失。

3.3 纹理加载的三重屏障与突破方案

离线环境下纹理加载失败率高达65%，远高于模型结构问题。这是因为纹理路径、格式、尺寸三重校验缺一不可：

第一重：路径解析屏障
Cesium的纹理加载器Cesium.TextureLoader默认用Resource类处理URI。当uri是/textures/0.jpg时，它会拼接成http://localhost/textures/0.jpg；但如果是textures/0.jpg（相对路径），它会基于当前HTML的<base>标签解析。很多开发者忘了在index.html里加<base href="/">，导致纹理请求发到http://localhost/current/path/textures/0.jpg而404。解决方案：在Viewer初始化前执行Cesium.Resource.setDefaultBaseUrl('/')。

第二重：MIME类型屏障
Nginx默认不识别.webp文件，返回Content-Type: application/octet-stream，Cesium会拒绝加载。必须在Nginx配置中添加：

types { image/webp webp; }

更稳妥的做法是：用Python的mimetypes库批量检查所有纹理文件的MIME类型，对非标准类型（如image/jp2）强制转为WebP。

第三重：尺寸对齐屏障
Cesium要求纹理尺寸必须是2的幂，且长宽比为1:1（正方形）。但倾斜摄影的原始纹理常是1920×1080这样的矩形。强行拉伸会导致模型扭曲。我的处理流程是：

1. 用OpenCV读取纹理，获取原始尺寸；
2. 计算下一个2的幂：size = 2 ** np.ceil(np.log2(max(w,h)))；
3. 用cv2.copyMakeBorder在短边补黑边，保持长宽比；
4. 保存为WebP，质量设为85（平衡体积与画质）。

实测表明，补黑边比拉伸变形的接受度高得多——甲方看到黑边会说“这是正常现象”，看到扭曲的玻璃幕墙会直接质疑数据质量。

注意：补边必须用纯黑（#000000），不能用透明。Cesium的WebGL渲染管线对Alpha通道处理不稳定，透明边会导致Z-fighting闪烁。

4. 实操全流程：从OSGB源数据到可交付离线包

4.1 准备工作：环境搭建与工具链安装

所有操作均在Ubuntu 22.04 LTS下完成，Windows用户请用WSL2，macOS用户确保Xcode命令行工具已安装。工具链选择原则：开源、CLI友好、社区活跃。

必需工具：

• 3d-tiles-tools（v1.12.0）：官方维护的3DTiles处理工具集，npm install -g 3d-tiles-tools
• gdal-bin（v3.4.3）：地理坐标系转换核心，sudo apt install gdal-bin
• potreeconverter（v2.1）：OSGB转点云的备用方案，git clone https://github.com/potree/PotreeConverter && cd PotreeConverter && make
• ffmpeg（v4.4.2）：视频纹理抽帧，sudo apt install ffmpeg
• Python 3.9+：自定义脚本主力，需安装numpy,opencv-python,pygltflib,pyproj

关键配置检查：

1. gdalinfo --version必须输出GDAL 3.4.3，旧版本不支持+proj=utm +zone=50 +datum=WGS84的完整参数；
2. 3d-tiles-tools --version必须≥1.10.0，低于此版本不支持--output-directory参数；
3. node -v必须≥16.14.0，Node.js 14对ES6模块支持不全，会导致3d-tiles-tools崩溃。

提示：不要用conda安装gdal，它会与系统gdal冲突。用apt安装后，用which gdal_translate确认路径是/usr/bin/gdal_translate。

4.2 第一步：OSGB源数据预处理与坐标系校准

客户给的OSGB数据通常来自ContextCapture或Pix4D，文件结构为：

project.osgb/ ├── Data/ │ ├── 0/ │ │ ├── 0.osgb │ │ └── 1.osgb │ └── 1/ ├── Metadata.xml └── project.xml

步骤1：提取控制点坐标
Metadata.xml里有<CoordinateSystem>节点，但常为空。此时必须联系客户获取WGS84控制点。假设客户提供3个点：

Point1: WGS84(116.397, 39.909) → Local(500123.45, 4642109.87) Point2: WGS84(116.398, 39.908) → Local(500234.56, 4642000.12) Point3: WGS84(116.399, 39.907) → Local(500345.67, 4641890.34)

用PROJ命令行计算七参数：

echo "116.397 39.909 0" | cs2cs +init=epsg:4326 +to +proj=utm +zone=50 +datum=WGS84 # 输出：500123.45 4642109.87 0.00

验证三个点是否匹配，若RMSE > 0.5米，说明控制点有误或坐标系理解错误。

步骤2：OSGB转3DTiles
用3d-tiles-tools的osgb-to-3dtiles命令：

osgb-to-3dtiles \ --input project.osgb \ --output tiles \ --max-simulataneous-requests 4 \ --tileset-name "city_model" \ --geometric-error 100 \ --output-format b3dm

关键参数说明：

• --max-simulataneous-requests 4：限制并发，防止内存溢出（16GB内存机器建议≤4）；
• --geometric-error 100：初始LOD阈值，后续会重写；
• --output-format b3dm：强制输出b3dm，不选glb（glb不支持batch table）。

步骤3：重写tileset.json坐标系
生成的tileset.json里root.transform是单位矩阵。用Python脚本注入ECEF转换矩阵：

import pyproj import numpy as np # WGS84转ECEF transformer = pyproj.Transformer.from_crs( "EPSG:4326", "EPSG:4978", # ECEF always_xy=True ) # 取控制点1的WGS84坐标 ecef = transformer.transform(116.397, 39.909, 0) # ecef = [x, y, z] 单位米 # 构建4x4平移矩阵（简化版，实际需七参数） transform_matrix = np.eye(4) transform_matrix[0, 3] = ecef[0] transform_matrix[1, 3] = ecef[1] transform_matrix[2, 3] = ecef[2] # 写入tileset.json with open("tiles/tileset.json") as f: data = json.load(f) data["root"]["transform"] = transform_matrix.flatten().tolist() with open("tiles/tileset.json", "w") as f: json.dump(data, f, indent=2)

4.3 第二步：纹理优化与路径标准化

步骤1：批量转换纹理格式
原始纹理在tiles/textures/目录下，多为PNG。用ImageMagick批量转WebP：

mkdir -p tiles_webp/textures for f in tiles/textures/*.png; do filename=$(basename "$f" .png) convert "$f" -quality 85 -define webp:lossless=false "tiles_webp/textures/${filename}.webp" done

注意：-define webp:lossless=false强制有损压缩，否则WebP体积不降反升。

步骤2：重写tileset.json纹理路径
用sed命令全局替换：

sed -i 's/\.png/.webp/g' tiles_webp/tileset.json sed -i 's/textures\//\/textures\//g' tiles_webp/tileset.json

但这样不够，因为b3dm内部的纹理URI也在GLB的images数组里。必须用pygltflib深度修改：

from pygltflib import GLTF2 import os for b3dm_file in Path("tiles_webp").rglob("*.b3dm"): # 解析b3dm，提取GLB glb_data = extract_glb_from_b3dm(b3dm_file) gltf = GLTF2().load_bytes(glb_data) # 修改所有images.uri for img in gltf.images: if img.uri and img.uri.endswith('.png'): img.uri = img.uri.replace('.png', '.webp') # 保存回b3dm new_glb = gltf.export_binary() new_b3dm = rebuild_b3dm_header(new_glb, b3dm_file) new_b3dm.save(b3dm_file)

步骤3：Nginx配置验证
创建nginx.conf：

events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; server { listen 8080; server_name localhost; location / { root /path/to/tiles_webp; index index.html; } location /textures/ { alias /path/to/tiles_webp/textures/; } } }

启动：nginx -c /path/to/nginx.conf -p /path/to/nginx/。用curl测试：curl http://localhost:8080/tileset.json应返回JSON，curl http://localhost:8080/textures/0.webp应返回二进制数据。

4.4 第三步：Cesium Viewer集成与环境适配

index.html核心代码：

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no"> <title>离线倾斜摄影</title> <script src="https://cesium.com/downloads/cesiumjs/releases/1.107/Build/Cesium/Cesium.js"></script> <link rel="stylesheet" href="https://cesium.com/downloads/cesiumjs/releases/1.107/Build/Cesium/Widgets/widgets.css"> </head> <body> <div id="cesiumContainer"></div> <script> // 环境探测 const isOffline = window.location.protocol === 'file:' || (window.location.hostname === 'localhost' && window.location.port === ''); // 离线专用配置 if (isOffline) { Cesium.Ion.defaultAccessToken = ''; // 禁用Ion Cesium.Resource.defaultRetryCallback = () => 0; // 禁用重试 Cesium.Scene.globe.depthTestAgainstTerrain = false; // 关闭地形深度测试 } const viewer = new Cesium.Viewer('cesiumContainer', { terrainProvider: Cesium.createWorldTerrain(), // 仍用在线地形，离线时自动降级 baseLayerPicker: false, geocoder: false, homeButton: false, sceneModePicker: false, selectionIndicator: false, infoBox: false, timeline: false, animation: false, shouldAnimate: false }); // 加载离线倾斜模型 const tileset = viewer.scene.primitives.add( new Cesium.Cesium3DTileset({ url: isOffline ? '/tileset.json' : 'https://online-server/tileset.json', maximumScreenSpaceError: 1, skipLevelOfDetail: true, baseScreenSpaceError: 1000, skipLevels: 1, dynamicScreenSpaceError: false, dynamicScreenSpaceErrorDensity: 0.00278 }) ); viewer.flyTo(tileset, { offset: new Cesium.HeadingPitchRange(0, -0.5, 500) }); </script> </body> </html>

关键适配点：

• maximumScreenSpaceError: 1：离线时LOD切换更激进，减少瓦片请求数；
• skipLevelOfDetail: true：跳过中间LOD，直接加载最细粒度；
• dynamicScreenSpaceError: false：禁用动态误差计算，用固化值；
• Cesium.createWorldTerrain()：即使离线，Cesium也会尝试加载在线地形，但失败后自动回退到无地形模式，不影响模型显示。

4.5 第四步：交付包制作与现场部署 checklist

交付给客户的不是一堆文件，而是一个可执行的离线包。我们用Electron封装，确保Windows/macOS/Linux三端一致。

Electron打包流程：

1. 初始化项目：npm init -y && npm install electron --save-dev
2. 创建main.js：

const { app, BrowserWindow } = require('electron') const path = require('path') function createWindow () { const win = new BrowserWindow({ width: 1200, height: 800, webPreferences: { nodeIntegration: true, contextIsolation: false, webSecurity: false // 关键！允许file://协议加载本地资源 } }) win.loadFile('index.html') } app.whenReady().then(createWindow)

3. package.json添加：

"main": "main.js", "scripts": { "start": "electron .", "build": "electron-builder" }, "build": { "appId": "com.example.cesium-offline", "win": {"target": "nsis"}, "mac": {"target": "dmg"}, "linux": {"target": "AppImage"} }

现场部署checklist（必做10项）：

1. ✅ 检查客户电脑显卡驱动是否支持WebGL2（用https://get.webgl.org/webgl2/测试）；
2. ✅ 确认磁盘剩余空间 ≥ 模型体积×1.5（缓存需要）；
3. ✅ 关闭杀毒软件实时监控（某些国产软件会拦截b3dm文件）；
4. ✅ 用chrome://gpu确认WebGL2已启用；
5. ✅ 测试USB3.0读取速度（≥80MB/s），低于此值需提醒客户用SSD；
6. ✅ 验证Nginx日志：tail -f /var/log/nginx/access.log，确认所有tileset.json/b3dm/webp请求状态码为200；
7. ✅ 在控制台执行Cesium.getBaseUri()，确认返回file:///或http://localhost:8080/；
8. ✅ 用viewer.scene.globe.show = false临时关闭地球，排除地形干扰；
9. ✅ 检查模型包围盒：console.log(tileset.boundingSphere)，确认center坐标在合理范围；
10. ✅ 最后一步：拔掉网线，重启浏览器，从头加载——这才是真正的离线测试。

5. 常见问题与排查技巧实录：那些深夜调试的血泪教训

5.1 白模问题速查表（90%的离线失败源于此）

独家技巧：当白模时，先在控制台执行：

// 强制加载根瓦片 const tileset = viewer.scene.primitives.get(0); tileset._root.tileLoadQueue = []; tileset._root.load();

如果根瓦片能显示，说明问题在children结构；如果仍白模，问题在root层。

5.2