blender-export

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Blender 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:
  • .usd
    — text-based (debuggable, large)
  • .usdc
    — binary (compact, fast — default choice)
  • .usda
    — ASCII (human-readable, larger)
  • .usdz
    — zipped USD with all assets (Apple AR / iOS)
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
    — 二进制格式(紧凑、速度快 — 默认选择
  • .usda
    — ASCII格式(人类可读、体积大)
  • .usdz
    — 包含所有资源的压缩USD(Apple AR / iOS专用)

Recipe 7 — Pre-export checklist (run before any export)

方案7 — 导出前检查清单(任何导出前执行)

python
import bpy
python
import bpy

1. 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)}")
undefined
mesh = obj.data print(f"export_check:{obj.name} verts:{len(mesh.vertices)} faces:{len(mesh.polygons)}")
undefined

Recipe 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
Bash
tool:
ls -la /tmp/output.glb
.
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")
导出后务必验证。可使用Bash工具:
ls -la /tmp/output.glb

Polycount targets per platform

各平台多边形数量目标

PlatformTargetNotes
Web (glTF)≤ 30 000 trisMobile-safe
Hero web asset≤ 60 000 trisDesktop OK
Unity / Unreal hero50 000–100 000 trisHigh-end
Mobile game≤ 10 000 trisPer asset
AR USDZ≤ 50 000 trisiOS recommendation
3D printunlimitedBut export size matters
平台目标值说明
网页(glTF)≤ 30 000 三角面适配移动端
网页核心资产≤ 60 000 三角面适配桌面端
Unity / Unreal核心资产50 000–100 000 三角面高端配置
移动游戏≤ 10 000 三角面单资产限制
AR USDZ≤ 50 000 三角面iOS官方推荐
3D打印无限制但导出文件大小会影响处理速度

Common pitfalls

常见问题

SymptomFix
FBX has no texturesSet
embed_textures=True, path_mode='COPY'
Procedural material missing in glTFBake to image textures first; use only Principled BSDF
Game engine: model rotated 90°FBX:
axis_up='Y', axis_forward='-Z'
; glTF:
export_yup=True
Game engine: model 100× too largeApply Transform; check unit scale
OBJ won't import elsewhereStick to ASCII filenames
STL won't printMake Manifold; recompute normals
GLB > 15 MBApply Decimate (Recipe 2); reduce textures to 1024×1024
Bone count exceededLimit weights to 4 per vertex; reduce bone count
Animation didn't exportglTF:
export_animations=True
; FBX:
bake_anim=True
症状修复方法
FBX文件无纹理设置
embed_textures=True, path_mode='COPY'
glTF中丢失程序化材质先烘焙为图像纹理;仅使用Principled BSDF材质
游戏引擎中模型旋转90°FBX:设置
axis_up='Y', axis_forward='-Z'
;glTF:设置
export_yup=True
游戏引擎中模型尺寸过大100倍应用变换;检查单位比例
OBJ无法在其他软件导入使用ASCII文件名
STL无法打印执行流形化;重新计算法线
GLB文件超过15 MB应用精简多边形(方案2);将纹理尺寸缩小至1024×1024
骨骼数量超限限制每个顶点的权重数量为4;减少骨骼数量
动画未导出glTF:设置
export_animations=True
;FBX:设置
bake_anim=True

When to load
references/overview.md

何时加载
references/overview.md

Load 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合成、各平台多边形数量目标。