blender-export
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBlender Export
Blender 导出
Export to the right format with the right settings. Wrong format choice = days of debugging in the target platform.
使用正确的设置导出至合适的格式。格式选择错误会导致在目标平台上花费数天时间调试。
Format decision tree
格式决策树
Where is this going?
├── Web (Three.js, Babylon.js, model-viewer, AR Quick Look) → glTF / GLB
├── Game engine (Unity, Unreal, Godot)
│ ├── Animated/rigged → FBX (or glTF for modern engines)
│ └── Static → OBJ or FBX or glTF
├── Apple AR (USDZ) → USDZ (special, see Recipe 6)
├── 3D printing → STL (geometry only, must be watertight)
├── VFX pipeline (Maya, Houdini, Nuke) → USD
└── DCC roundtrip → FBX (industry standard)Quick rule for unknown target: glTF / GLB. Open standard, modern, universally supported.
目标平台是什么?
├── 网页(Three.js、Babylon.js、model-viewer、AR Quick Look)→ glTF / GLB
├── 游戏引擎(Unity、Unreal、Godot)
│ ├── 带动画/绑定骨骼 → FBX(现代引擎也可使用glTF)
│ └── 静态模型 → OBJ 或 FBX 或 glTF
├── Apple AR(USDZ)→ USDZ(特殊格式,参见方案6)
├── 3D打印 → STL(仅保留几何体,必须是密闭网格)
├── 视觉特效管线(Maya、Houdini、Nuke)→ USD
└── DCC软件往返协作 → FBX(行业标准)未知目标平台的快速规则:选择glTF / GLB。开放标准、现代化、支持范围广。
Recipes
操作方案
Recipe 1 — glTF / GLB export (web / AR / general)
方案1 — glTF / GLB导出(网页/增强现实/通用场景)
python
import bpy
bpy.ops.export_scene.gltf(
filepath='/tmp/output.glb',
export_format='GLB', # single-file binary; preferred
export_apply=True, # apply modifiers before export
export_materials='EXPORT',
export_image_format='AUTO', # PNG; AUTO falls back to JPEG for opaque images
export_yup=True, # Y-up convention (most engines / web expect this)
export_animations=True, # toggle off for static models
export_morph=True, # shape keys
export_skins=True, # armatures + weights
export_normals=True,
export_tangents=False, # skip unless target uses tangent-space normals beyond standard
)python
import bpy
bpy.ops.export_scene.gltf(
filepath='/tmp/output.glb',
export_format='GLB', # 单文件二进制格式;优先选择
export_apply=True, # 导出前应用修改器
export_materials='EXPORT',
export_image_format='AUTO', # PNG格式;AUTO会为不透明图像自动 fallback 到JPEG
export_yup=True, # Y轴向上约定(多数引擎/网页遵循此标准)
export_animations=True, # 静态模型可关闭此选项
export_morph=True, # 形状键
export_skins=True, # 骨骼绑定 + 权重
export_normals=True,
export_tangents=False, # 除非目标平台需要超出标准的切线空间法线,否则跳过
)Verify
验证
import os
size_mb = os.path.getsize('/tmp/output.glb') / (1024 * 1024)
print(f"export:gltf {size_mb:.2f} MB")
**glTF caveats**:
- Only Principled BSDF materials export cleanly. Procedural shaders are dropped or simplified.
- Hard cap: 15 MB; soft target: 8 MB.
- No KTX2 / Draco compression (unless target supports those loaders).
- PNG textures only (max 1024×1024 typical).import os
size_mb = os.path.getsize('/tmp/output.glb') / (1024 * 1024)
print(f"export:gltf {size_mb:.2f} MB")
**glTF注意事项**:
- 仅Principled BSDF材质能完整导出。程序化着色器会被丢弃或简化。
- 硬限制:15 MB;理想目标:8 MB。
- 不支持KTX2 / Draco压缩(除非目标平台支持对应加载器)。
- 仅支持PNG纹理(通常最大尺寸为1024×1024)。Recipe 2 — Decimate before export (if too large)
方案2 — 导出前精简多边形(文件过大时)
python
import bpy
obj = bpy.data.objects['GEO-target']
bpy.context.view_layer.objects.active = obj
mod = obj.modifiers.new('Decimate', type='DECIMATE')
mod.ratio = 0.7 # keep 70% of faces; lower = more reduction
mod.use_collapse_degenerate = True
bpy.ops.object.modifier_apply(modifier=mod.name)
print(f"decimated:{obj.name} verts:{len(obj.data.vertices)}")Then re-export. Iterate ratio until file size fits target.
python
import bpy
obj = bpy.data.objects['GEO-target']
bpy.context.view_layer.objects.active = obj
mod = obj.modifiers.new('Decimate', type='DECIMATE')
mod.ratio = 0.7 # 保留70%的面;数值越低,精简程度越高
mod.use_collapse_degenerate = True
bpy.ops.object.modifier_apply(modifier=mod.name)
print(f"decimated:{obj.name} verts:{len(obj.data.vertices)}")之后重新导出。调整ratio值直到文件大小符合目标平台要求。
Recipe 3 — FBX export (game engines)
方案3 — FBX导出(游戏引擎)
python
import bpy
bpy.ops.export_scene.fbx(
filepath='/tmp/output.fbx',
use_selection=False,
apply_unit_scale=True,
apply_scale_options='FBX_SCALE_ALL',
bake_space_transform=True, # critical: applies rotation to mesh
object_types={'MESH', 'ARMATURE', 'EMPTY'},
use_mesh_modifiers=True,
mesh_smooth_type='FACE',
use_armature_deform_only=True,
bake_anim=True,
bake_anim_use_all_bones=True,
bake_anim_use_nla_strips=True,
bake_anim_use_all_actions=True,
bake_anim_force_startend_keying=True,
embed_textures=True, # critical: embed textures into FBX
path_mode='COPY',
axis_forward='-Z',
axis_up='Y',
)
print('export:fbx')Common FBX gotchas:
- Model rotated 90° in target → check
axis_up='Y', axis_forward='-Z' - Model 100× too large → Apply Transform on the object before export
- Textures missing →
embed_textures=True, path_mode='COPY' - Animation only plays one action → use NLA + bake all actions
python
import bpy
bpy.ops.export_scene.fbx(
filepath='/tmp/output.fbx',
use_selection=False,
apply_unit_scale=True,
apply_scale_options='FBX_SCALE_ALL',
bake_space_transform=True, # 关键设置:将旋转信息烘焙到网格中
object_types={'MESH', 'ARMATURE', 'EMPTY'},
use_mesh_modifiers=True,
mesh_smooth_type='FACE',
use_armature_deform_only=True,
bake_anim=True,
bake_anim_use_all_bones=True,
bake_anim_use_nla_strips=True,
bake_anim_use_all_actions=True,
bake_anim_force_startend_keying=True,
embed_textures=True, # 关键设置:将纹理嵌入FBX文件
path_mode='COPY',
axis_forward='-Z',
axis_up='Y',
)
print('export:fbx')FBX常见问题:
- 模型在目标平台中旋转90° → 检查设置
axis_up='Y', axis_forward='-Z' - 模型尺寸过大100倍 → 导出前对物体应用变换
- 纹理丢失 → 设置
embed_textures=True, path_mode='COPY' - 动画仅播放一个动作 → 使用NLA并烘焙所有动作
Recipe 4 — OBJ export (simple / universal)
方案4 — OBJ导出(简单/通用场景)
python
import bpy
bpy.ops.wm.obj_export(
filepath='/tmp/output.obj',
export_animation=False,
apply_modifiers=True,
export_eval_mode='DAG_EVAL_VIEWPORT',
export_uv=True,
export_normals=True,
export_materials=True,
export_triangulated_mesh=False,
forward_axis='NEGATIVE_Z',
up_axis='Y',
)
print('export:obj')OBJ has no animation, no rigging, basic material support only. Use for simple geometry exchange.
python
import bpy
bpy.ops.wm.obj_export(
filepath='/tmp/output.obj',
export_animation=False,
apply_modifiers=True,
export_eval_mode='DAG_EVAL_VIEWPORT',
export_uv=True,
export_normals=True,
export_materials=True,
export_triangulated_mesh=False,
forward_axis='NEGATIVE_Z',
up_axis='Y',
)
print('export:obj')OBJ格式不支持动画、骨骼绑定,仅支持基础材质。适用于简单几何体交换。
Recipe 5 — STL export (3D printing)
方案5 — STL导出(3D打印)
python
import bpy
bpy.ops.wm.stl_export(
filepath='/tmp/output.stl',
ascii_format=False, # binary STL (smaller, faster)
apply_modifiers=True,
)
print('export:stl')Critical for STL:
- Mesh must be watertight (no holes, no flipped normals, no internal faces).
- Pre-export: in Edit Mode, run .
Mesh → Clean Up → Make Manifold - STL has NO units — most slicers assume mm. Set Blender scene units to mm before modeling.
- STL has NO color/material — single-color grey only.
python
import bpy
bpy.ops.wm.stl_export(
filepath='/tmp/output.stl',
ascii_format=False, # 二进制STL(体积更小、速度更快)
apply_modifiers=True,
)
print('export:stl')STL关键要求:
- 网格必须是密闭的(无孔洞、无翻转法线、无内部面)。
- 导出前:在编辑模式下执行。
网格 → 清理 → 流形化 - STL无单位信息——大多数切片软件默认使用毫米。建模前需将Blender场景单位设置为毫米。
- STL无颜色/材质信息——仅支持单一灰色。
Recipe 6 — USD export (VFX pipeline)
方案6 — USD导出(视觉特效管线)
python
import bpy
bpy.ops.wm.usd_export(
filepath='/tmp/scene.usdc',
export_animation=True,
export_uvmaps=True,
export_normals=True,
export_materials=True,
use_instancing=True,
export_textures=True,
overwrite_textures=True,
)
print('export:usd')USD variants:
- — text-based (debuggable, large)
.usd - — binary (compact, fast — default choice)
.usdc - — ASCII (human-readable, larger)
.usda - — zipped USD with all assets (Apple AR / iOS)
.usdz
python
import bpy
bpy.ops.wm.usd_export(
filepath='/tmp/scene.usdc',
export_animation=True,
export_uvmaps=True,
export_normals=True,
export_materials=True,
use_instancing=True,
export_textures=True,
overwrite_textures=True,
)
print('export:usd')USD格式变体:
- — 文本格式(可调试、体积大)
.usd - — 二进制格式(紧凑、速度快 — 默认选择)
.usdc - — ASCII格式(人类可读、体积大)
.usda - — 包含所有资源的压缩USD(Apple AR / iOS专用)
.usdz
Recipe 7 — Pre-export checklist (run before any export)
方案7 — 导出前检查清单(任何导出前执行)
python
import bpypython
import bpy1. Apply transforms (rotation + scale baked into geometry)
1. 应用变换(将旋转和缩放信息烘焙到几何体)
obj = bpy.data.objects['GEO-target']
bpy.context.view_layer.objects.active = obj
bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)
obj = bpy.data.objects['GEO-target']
bpy.context.view_layer.objects.active = obj
bpy.ops.object.transform_apply(location=False, rotation=True, scale=True)
2. Recompute normals
2. 重新计算法线
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.normals_make_consistent(inside=False)
bpy.ops.mesh.remove_doubles(threshold=0.0001)
bpy.ops.object.mode_set(mode='OBJECT')
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.normals_make_consistent(inside=False)
bpy.ops.mesh.remove_doubles(threshold=0.0001)
bpy.ops.object.mode_set(mode='OBJECT')
3. Apply modifiers (some exporters keep them, but for portability apply before export)
3. 应用修改器(部分导出器会保留修改器,但为了兼容性建议导出前应用)
Already done via export_apply=True / use_mesh_modifiers=True flags
已通过export_apply=True / use_mesh_modifiers=True参数设置完成
4. Verify mesh stats
4. 验证网格统计信息
mesh = obj.data
print(f"export_check:{obj.name} verts:{len(mesh.vertices)} faces:{len(mesh.polygons)}")
undefinedmesh = obj.data
print(f"export_check:{obj.name} verts:{len(mesh.vertices)} faces:{len(mesh.polygons)}")
undefinedRecipe 8 — Verify exported file
方案8 — 验证导出文件
python
import os
filepath = '/tmp/output.glb'
if not os.path.exists(filepath):
print(f"ERROR:not_found {filepath}")
else:
size_mb = os.path.getsize(filepath) / (1024 * 1024)
print(f"verified:{filepath} {size_mb:.2f}MB")Always verify after export. Use tool: .
Bashls -la /tmp/output.glbpython
import os
filepath = '/tmp/output.glb'
if not os.path.exists(filepath):
print(f"ERROR:not_found {filepath}")
else:
size_mb = os.path.getsize(filepath) / (1024 * 1024)
print(f"verified:{filepath} {size_mb:.2f}MB")导出后务必验证。可使用Bash工具:。
ls -la /tmp/output.glbPolycount targets per platform
各平台多边形数量目标
| Platform | Target | Notes |
|---|---|---|
| Web (glTF) | ≤ 30 000 tris | Mobile-safe |
| Hero web asset | ≤ 60 000 tris | Desktop OK |
| Unity / Unreal hero | 50 000–100 000 tris | High-end |
| Mobile game | ≤ 10 000 tris | Per asset |
| AR USDZ | ≤ 50 000 tris | iOS recommendation |
| 3D print | unlimited | But export size matters |
| 平台 | 目标值 | 说明 |
|---|---|---|
| 网页(glTF) | ≤ 30 000 三角面 | 适配移动端 |
| 网页核心资产 | ≤ 60 000 三角面 | 适配桌面端 |
| Unity / Unreal核心资产 | 50 000–100 000 三角面 | 高端配置 |
| 移动游戏 | ≤ 10 000 三角面 | 单资产限制 |
| AR USDZ | ≤ 50 000 三角面 | iOS官方推荐 |
| 3D打印 | 无限制 | 但导出文件大小会影响处理速度 |
Common pitfalls
常见问题
| Symptom | Fix |
|---|---|
| FBX has no textures | Set |
| Procedural material missing in glTF | Bake to image textures first; use only Principled BSDF |
| Game engine: model rotated 90° | FBX: |
| Game engine: model 100× too large | Apply Transform; check unit scale |
| OBJ won't import elsewhere | Stick to ASCII filenames |
| STL won't print | Make Manifold; recompute normals |
| GLB > 15 MB | Apply Decimate (Recipe 2); reduce textures to 1024×1024 |
| Bone count exceeded | Limit weights to 4 per vertex; reduce bone count |
| Animation didn't export | glTF: |
| 症状 | 修复方法 |
|---|---|
| FBX文件无纹理 | 设置 |
| glTF中丢失程序化材质 | 先烘焙为图像纹理;仅使用Principled BSDF材质 |
| 游戏引擎中模型旋转90° | FBX:设置 |
| 游戏引擎中模型尺寸过大100倍 | 应用变换;检查单位比例 |
| OBJ无法在其他软件导入 | 使用ASCII文件名 |
| STL无法打印 | 执行流形化;重新计算法线 |
| GLB文件超过15 MB | 应用精简多边形(方案2);将纹理尺寸缩小至1024×1024 |
| 骨骼数量超限 | 限制每个顶点的权重数量为4;减少骨骼数量 |
| 动画未导出 | glTF:设置 |
When to load references/overview.md
references/overview.md何时加载references/overview.md
references/overview.mdLoad when:
- Multi-format batch export needed
- Asset Browser / library override workflow
- USDZ for Apple AR specifics
- Game engine roundtrip troubleshooting (Unity/Unreal-specific quirks)
- LOD generation strategy
The reference covers: per-format pitfalls, asset browser workflow, library overrides for production, USD composition, polycount targets per platform.
在以下场景加载:
- 需要批量导出多格式文件
- 使用资源浏览器/库覆盖工作流
- 针对Apple AR的USDZ格式细节
- 游戏引擎往返协作故障排查(Unity/Unreal特有问题)
- LOD生成策略
参考文档涵盖:各格式陷阱、资源浏览器工作流、生产环境库覆盖、USD合成、各平台多边形数量目标。