Blender插件开发实战：修复Cats插件Bug并构建Unity自动化导出工具

最近在开发一个涉及 Blender 到 Unity 工作流的项目时，遇到了一个棘手的问题：社区中一个名为 “Cats” 的知名 Blender 插件在特定版本下出现了兼容性错误，导致模型修复和优化流程中断。这直接影响了从 Blender 导出高质量角色模型到 Unity 的效率和效果。为了解决这个问题，我深入研究了插件的源码，利用 OpenAI Codex 的代码补全与理解能力，成功定位并修复了核心 Bug。不仅如此，我还将修复过程与 Unity 导入需求相结合，开发了一个能够自动化、优化 Blender 到 Unity 模型导出流程的增强型插件。

本文将完整分享这次“修复+开发”的全过程。无论你是对 Blender 插件开发感兴趣的初学者，还是苦于 3D 美术与游戏引擎工作流对接的 TA（技术美术）或开发者，都能从中获得一套可复现的实战方案。我们将从问题定位、Codex 辅助调试、插件修复，一直讲到新插件的架构设计、代码实现与在 Unity 中的集成应用，最终实现一键式的高质量模型转换。

1. 背景与核心概念：Cats 插件与 Blender-Unity 工作流

在深入技术细节之前，有必要厘清几个核心概念，这有助于理解我们为什么要修复 Cats 以及新插件要解决什么问题。

Blender 是一款开源、免费的 3D 创作套件，广泛应用于建模、雕刻、动画等领域。其强大的社区生态催生了众多插件，极大地扩展了其功能边界。

Unity 是主流的实时 3D 开发平台，尤其在游戏和交互式内容开发中占据重要地位。一个常见的生产流程是：美术人员在 Blender 中创建 3D 模型和动画，然后导出并导入到 Unity 中进行场景搭建、逻辑编写和最终发布。

Cats Blender 插件 是社区中一款极具人气的工具，它的全称是 “Cat’s blender plugins”，但通常被称为 “Cats”。它的核心功能是专门针对 VRM 和 VRChat 模型进行优化和修复，例如：

• 模型修复：自动合并分离的网格、修复翻转的法线、移除零面积的无效面。
• 骨骼与权重优化：清理冗余的骨骼顶点组，优化骨骼权重分布。
• 材质与形状键处理：帮助整理材质球，处理形状键（Blend Shapes）的兼容性问题。
• 一键导出：简化针对特定平台（如 VRChat）的模型导出流程。

可以说，Cats 是许多 VRChat 创作者和希望快速处理人形模型的开发者不可或缺的工具。

Blender 到 Unity 的工作流痛点： 尽管 Blender 和 Unity 都支持通用的 .fbx 格式，但直接导出/导入往往会产生大量需要手动调整的问题，例如：

1. 轴向不一致：Blender 使用 Z-Up 坐标系，而 Unity 使用 Y-Up。直接导出可能导致模型在 Unity 中“躺倒”。
2. 缩放问题：Blender 默认单位为米，而 Unity 中一个单位通常也对应一米，但导出设置不当会导致模型缩放异常。
3. 材质丢失或错误：Blender 的材质系统（Cycles/Eevee）与 Unity 的材质（Standard/URP/HDRP）不直接兼容，需要重新关联或转换。
4. 骨骼与动画问题：骨骼的命名、旋转模式、动画曲线的插值方式可能导致动画在 Unity 中表现异常。
5. 多余数据：导出的 FBX 可能包含 Unity 不需要的冗余数据，如自定义属性、空物体等，增大文件体积。

我们新插件的目标，就是在修复 Cats 插件原有 Bug 的基础上，构建一个 “桥梁”式插件。它不仅能确保 Cats 的修复功能稳定运行，还能在 Blender 端就完成针对 Unity 的优化预处理，并生成一个“即插即用”的 Unity Package，极大简化美术与程序之间的协作成本。

2. 环境准备与版本说明

在开始编码之前，确保你的开发环境配置正确。版本兼容性是此类跨软件插件开发的首要问题。

Blender 端环境：

• Blender 版本：3.6 LTS (长期支持版)。这是目前社区插件兼容性最好的版本之一。我们的修复和开发基于此版本。请注意，Blender 4.0+ 的 API 有部分变动，若使用更高版本，可能需要微调代码。
• Python 环境：Blender 内置了 Python 解释器（如 3.10）。我们的插件将直接使用 Blender 的 Python API (bpy)，无需额外安装 Python。
• 代码编辑器：推荐使用 VS Code，并安装 Python 和 Blender 开发相关插件（如 Blender Development）。这能提供 API 智能提示和代码跳转。
• Cats 插件版本：0.19.0 (需要修复的版本)。我们将以此版本为基础进行修复和增强。

Unity 端环境：

• Unity 版本：2022.3 LTS。选择 LTS 版本能保证项目的长期稳定性。
• 渲染管线：本文示例基于内置渲染管线（Built-in RP），但原理同样适用于 URP/HDRP，只需调整材质部分。

开发工具与资源：

• OpenAI Codex / GitHub Copilot：作为辅助编程工具，用于快速理解现有代码、生成补全代码、重构函数。我们将演示如何有效地向 AI 描述问题以获得有用的代码片段。
• Blender Python API 文档：必备参考手册。离线版可集成到 VS Code 中。
• 一个用于测试的 Blender 角色模型文件（.blend），最好包含骨骼、权重和材质。

项目结构预览： 在开始前，我们先规划一下最终插件的工作目录结构，以便理解代码的组织方式。

3. 核心原理与 Cats 插件 Bug 分析

要修复并增强一个插件，必须首先理解其工作原理和问题所在。

3.1 Cats 插件核心模块分析

Cats 插件是一个庞大的工具集。通过阅读其源码（通常位于 Blender 的 scripts/addons 目录下），我们可以将其核心功能模块归纳如下：

1. 模型检查器 (Model Checker)：扫描模型存在的问题并生成报告。
2. 修复器 (Fix Model)：根据检查报告执行自动修复。
3. 骨骼工具 (Bone Tools)：处理骨骼合并、重命名、权重清理。
4. 材质工具 (Material Tools)：合并材质、转换图像纹理。
5. 导出器 (Export)：封装了针对 VRChat SDK 的 FBX 导出设置。

其代码结构通常是基于 Blender 的 bpy.types.Operator 类来定义每一个可执行的操作。

3.2 使用 Codex 辅助定位 Bug

我遇到的 Bug 具体表现为：在执行 “Merge Weights” （合并权重）功能时，Blender 控制台抛出 AttributeError: ‘NoneType’ object has no attribute ‘vertices’ 错误。

传统的调试方式是逐行阅读可能上千行的代码。而借助 Codex，我们可以大大加速这个过程。

步骤一：向 Codex 提供错误上下文 将错误日志和疑似相关的函数代码片段提供给 Codex。例如：

提示词示例：“以上是 Blender 插件中一个合并顶点权重函数的片段。当运行到 for vertex in obj.data.vertices: 循环时，有时会报错 ‘NoneType’ object has no attribute ‘vertices’。请分析可能的原因，并给出修复后的代码。”

Codex 的分析与建议（经过整理）：

1. 原因分析：错误表明 obj.data 为 None。在 Blender 中，一个 Object 的 data 属性是其关联的 Mesh, Armature 等数据块。它可能为 None 如果对象类型不匹配或数据被意外移除。尽管函数开头检查了 obj.type != ‘MESH’，但在多线程或特定操作顺序下，obj.data 仍可能被置空。
2. 修复方案：在访问 obj.data.vertices 之前，增加一个对