gltf-pipeline使用方法

关于 gltf-pipeline 的详细用法解析和实用指南。作为 glTF 官方团队开发的命令行工具，它集成了 Draco 压缩、纹理优化、量化等核心功能，是处理 GLB/glTF 模型的专业利器。

---

🔧 安装 gltf-pipeline

# 全局安装（推荐，方便命令行调用）
npm install -g gltf-pipeline

# 或使用 npx 临时运行（无需安装）
npx gltf-pipeline [参数]

---

🚀 核心命令与参数详解

基础格式：

gltf-pipeline -i [输入文件] -o [输出文件] [参数]

常用参数表：

参数	缩写	作用	示例值	注意
--draco.compressionLevel	-d	启用 Draco 压缩	-d 或 --draco.compressionLevel=10	必加运行时解码器
--draco.quantizePosition	-	Draco 顶点位置精度	16 (推荐)	值越低精度越差
--draco.quantizeNormal	-	Draco 法线精度	8 (推荐)	-
--draco.quantizeTexcoord	-	Draco UV 精度	8 (推荐)	-
--textureCompression	-t	纹理压缩为 Basis U	-t	生成 .ktx2 格式
--keepOriginalImages	-	保留原始纹理（调试用）	-	默认会删除
--quantizePosition	-qp	全局面部量化（非 Draco）	16	兼容性好
--quantizeNormal	-qn	全局法线量化	8	-
--quantizeTexcoord	-qt	全局 UV 量化	8	-
--compressTextures	-	使用 DEFLATE 压缩纹理	-	效果有限
--stats	-	显示压缩前后对比数据	-	必用！

---

🛠️ 经典使用场景示例

1. 基础 Draco 压缩（几何体瘦身）

gltf-pipeline -i model.glb -o compressed.glb -d

→ 输出文件减少 50%-90%，但需在项目中集成 Draco 解码器。

2. Draco + 纹理压缩（全面优化）

gltf-pipeline -i model.glb -o compressed.glb -d -t

→ 几何体用 Draco，纹理转 Basis U (.ktx2)，适合 WebGL 项目。

3. 高级控制（自定义精度+统计）

gltf-pipeline -i model.glb -o compressed.glb \
  -d \
  --draco.quantizePosition=14 \
  --draco.quantizeNormal=10 \
  --textureCompression \
  --stats

→ 调整 Draco 精度 + 输出压缩率报告。

4. 仅纹理压缩（兼容性方案）

gltf-pipeline -i model.glb -o compressed.glb -t

→ 当目标环境不支持 Draco 时使用（如旧浏览器）。

---

⚠️ 关键注意事项

1. Draco 解码器依赖
   压缩后的模型需在运行时加载 Draco 库：

   <!-- Three.js 示例 -->
   <script src="https://unpkg.com/three@latest/examples/jsm/libs/draco/gltf/draco_decoder.js"></script>
   

   // 在初始化时指定解码路径
   GLTFLoader.setDRACOLoader(new DRACOLoader().setDecoderPath('/path/to/'));
   

2. 纹理压缩格式选择
   -t 生成的 Basis U 纹理需浏览器支持 KHR_texture_basisu 扩展。测试工具：Babylon.js Sandbox

3. 避免文件意外增大
   使用 --keepOriginalImages 参数可能导致输出文件变大（保留原始 PNG/JPG + 新增 KTX2）。

---

📊 压缩效果验证

使用 --stats 参数查看优化报告：

gltf-pipeline -i dragon.glb -o dragon_compressed.glb -d -t --stats

输出示例：

原始文件: 15.6 MB
处理后: 2.1 MB (-86%)
纹理: 14.8 MB → 1.2 MB
网格: 0.8 MB → 0.4 MB

---

🔄 工作流建议

1. 原始模型 → Blender 导出为 glTF
   （确保材质/UV正确）
2. 终端执行压缩：

   gltf-pipeline -i input.glb -o output.glb -d -t --draco.compressionLevel=10
   

3. 测试渲染：
   用 Three.js GLTF Viewer 快速验证
4. 集成到项目：
   添加 Draco 解码器，加载 output.glb

💡 提示：与 glTF-Transform 配合使用可进一步优化（如合并材质、删除冗余节点）。