Blender插件开发全面教程

这是一份为你准备的 Blender 插件开发从零基础到入门的全面教程。即使你完全没有编程经验，借助AI工具(如ChatGPT或DeepSeek,Kimi,豆包)和这份指南，也能快速上手。

第一章：出发前的准备

在写第一行代码前，我们需要先把“工具箱”和“环境”准备好。正确的环境配置能让开发过程事半功倍。

1.1 必备知识

•Blender 基础操作：知道如何移动物体、添加修改器、使用面板。

•Python 基础：如果你完全不会 Python，建议花 30 分钟看一遍基础语法（变量、列表、循环、函数）。借助 AI，你可以直接问“用 Python 写一个循环遍历列表”来快速学习 。(点击这里-零基础学习Python)

1.2 环境配置

为了更容易排查错误，我们需要让 Blender 把“后台报错”显示出来：

1. 打开系统控制台：

 • Windows：打开 Blender，点击顶部菜单 窗口 -> 切换系统控制台。这会弹出一个黑色的命令行窗口，代码报错会显示在这里。

 • Mac：需要在应用程序文件夹中找到 Blender，右键选择“显示包内容”，进入 Contents/MacOS 双击运行 Blender 来启动终端 。

2. 开启开发者选项：

•进入 编辑 -> 偏好设置 -> 界面。

•勾选 显示开发人员选项。这会在右键菜单中增加“编辑源码”等便捷功能 。

3. 选择代码编辑器：

•方案A(新手推荐)：Blender 自带的 文本编辑器 工作区。可以直接运行脚本，非常简单。

•方案B(专业)：VS Code。配合 Blender Development 插件，可以实现代码补全和一键发送代码到 Blender 执行 。

---

第二章：第一个插件

任何插件都需要一个“身份证”和基本的“开关”逻辑。

2.1 插件的最简结构

在 Blender 的文本编辑器中，输入以下代码。这是一个什么功能都没有，但能被 Blender 识别为插件的空壳：

bl_info = {    “name”: “我的第一个插件”,    “author”: “你的名字”,    “version”: (1, 0),    “blender”: (4, 2, 0),    “location”: “View3D > UI”,    “category”: “Object”,}import bpydef register():    print(“插件已启用，你好！”)def unregister():    print(“插件已禁用，再见！”)if __name__ == “__main__”:    register()

代码详解：

•bl_info：这是一个字典，告诉 Blender 插件叫什么、作者是谁、最低支持哪个版本。注意：在 Blender 4.2 及以上版本，虽然也支持这种方式，但官方推荐转为扩展格式(需要 blender_manifest.toml 文件)。

•register：当你勾选启用插件时，会运行这里的代码。

•unregister：当你取消勾选禁用插件时，会运行这里的代码。

2.2 运行与安装

1. 在文本编辑器里点击 运行脚本 按钮。

2. 由于我们没有实际安装，仅仅运行脚本不会看到插件出现在偏好设置里。

3. 正式安装：将上述代码保存为 .py 文件（例如 my_first_addon.py）。然后进入 编辑 -> 偏好设置 -> 插件 -> 安装，选择你的文件，勾选启用 。

---

第三章：添加功能（操作符 Operator）

插件里最核心的是 Operator(操作符)，它代表用户点击按钮后执行的动作。

3.1 案例：一键移动物体

我们来实现一个让所有选中的物体沿 X 轴移动 1 米的按钮。

import bpy# 1. 定义一个操作符类class MOVE_OT_my_operator(bpy.types.Operator):    “””提示信息：鼠标悬停时会显示这个文档字符串”””     bl_idname = “object.my_move_operator”  # 唯一标识符，用于调用    bl_label = “向右移动一格”              # 界面显示的名字    bl_options = {‘REGISTER’, ‘UNDO’}     # 支持撤销    # 2. 执行函数：点按钮时触发    def execute(self, context):        # 获取当前选中的物体        for obj in context.selected_objects:            # 修改位置            obj.location.x += 1.0        # 返回成功信号        return {‘FINISHED’}# 3. 注册与注销def register():    bpy.utils.register_class(MOVE_OT_my_operator)def unregister():    bpy.utils.unregister_class(MOVE_OT_my_operator)if __name__ == “__main__”:    register()

如何调用：

•临时调用：按F3打开搜索菜单，输入 “向右移动一格”，回车执行。

•添加按钮：如果想在侧边栏加个按钮，需要在register函数中添加面板代码（见第四章）。

---

第四章：添加界面（面板 Panel）

插件通常需要放在侧边栏(按N键呼出)里方便点击。

4.1 创建自定义面板

结合上面的操作符，我们创建一个面板来放按钮。

import bpy#假设上面的操作符类 MOVE_OT_my_operator 已经定义好了class VIEW3D_PT_my_panel(bpy.types.Panel):    bl_label = “我的工具集”    bl_idname = “VIEW3D_PT_my_panel”    bl_space_type = ‘VIEW_3D’    # 显示在 3D 视图中    bl_region_type = ‘UI’        # 显示在侧边栏    bl_category = “我的工具”      # 侧边栏的标签页名称    def draw(self, context):        layout = self.layout        # 创建一个按钮，点击后运行我们的操作符        layout.operator(“object.my_move_operator”)# 注册时要同时注册面板和操作符def register():    bpy.utils.register_class(MOVE_OT_my_operator)    bpy.utils.register_class(VIEW3D_PT_my_panel)def unregister():    bpy.utils.unregister_class(VIEW3D_PT_my_panel)    bpy.utils.unregister_class(MOVE_OT_my_operator)if __name__ == “__main__”:    register()

---

第五章：让插件更专业（属性与配置）

我们不能让总数固定为 10。我们需要添加一个滑块，让用户在界面里调整数值。

5.1 添加属性

属性需要定义在bpy.types.PropertyGroup里，然后挂在 Blender 的某个数据结构上（比如场景）。

# 1. 定义属性组class MyProperties(bpy.types.PropertyGroup):    my_int: bpy.props.IntProperty(        name=“阵列数量”,        default=5,        min=1,        max=100    )    my_float: bpy.props.FloatProperty(        name=“移动距离”,        default=1.0,        subtype=‘DISTANCE’  # 显示为距离单位    )# 2. 在注册时，将这个属性组挂载到 bpy.types.Scene 上def register():    bpy.utils.register_class(MyProperties)    bpy.types.Scene.my_tool_props = bpy.props.PointerProperty(type=MyProperties)def unregister():    del bpy.types.Scene.my_tool_props    bpy.utils.unregister_class(MyProperties)# 3. 在面板中显示这个滑块class VIEW3D_PT_my_panel(bpy.types.Panel):    # … (上面的代码)    def draw(self, context):        layout = self.layout        props = context.scene.my_tool_props  # 获取属性        # 添加滑块        layout.prop(props, “my_int”)        layout.prop(props, “my_float”)        layout.operator(“object.my_move_operator”)# 4. 在操作符中使用属性class MOVE_OT_my_operator(bpy.types.Operator):    def execute(self, context):        props = context.scene.my_tool_props        total = props.my_int        distance = props.my_float        for obj in context.selected_objects:            obj.location.x += distance        return {‘FINISHED’}

---

第六章：Blender 4.2 的新变化（扩展 Extensions）

从 Blender 4.2 开始，官方推荐使用扩展格式。如果你的插件是给 4.2 及以上版本用的，建议采用这种结构 。

6.1 文件结构

你不能再只有一个.py文件了，需要是一个文件夹，包含清单文件和代码：

my_awesome_addon/├── blender_manifest.toml   # 替代 bl_info└── __init__.py             # 主代码文件

6.2 清单文件内容

blender_manifest.toml 的内容如下：

id = “my_awesome_addon”

name = “我的超强插件”

maintainer = “你的名字”

type = “add-on”

version = “1.0.0”

blender_version_min = “4.2.0”

tagline = “这是一行简短的描述”

6.3 代码文件 __init__.py

代码结构基本不变，但需要注意相对导入和 __package__ 的使用 。

import bpydef register():    print(“扩展已加载”)def unregister():    print(“扩展已卸载”)

---

第七章：借助 AI 助手开发

这是你最大的优势。不要死记硬背 API，要学会和 AI 对话。

7.1 提问技巧

当你需要实现某个功能时，直接向 AI 提问：

•“在 Blender Python 中，如何获取当前选中的物体？”

•“写一段代码，创建一个立方体并把它移动到游标位置。”

•“如何在 Blender 插件中创建一个枚举下拉菜单？”

7.2 借助 AI 调试

如果代码报错，直接把红色报错信息和代码复制给 AI：

“我运行这段代码时出现了 AttributeError: ‘NoneType’ object has no attribute ‘location’，为什么？”

AI 会告诉你：“你没有检查当前是否有活动物体，如果场景是空的就会报错。请加上 if context.active_object is not None:。”

7.3 让 AI 写完整代码

你可以像这样给 AI 下指令：

“请帮我写一个 Blender 插件，功能是：在 3D 视图的侧边栏添加一个面板，面板里有一个‘生成随机立方体’按钮。每次点击按钮，就在 3D 游标位置生成立方体，且立方体的大小随机在 0.5 到 2.0 之间。”

---

第八章：调试与发布

8.1 调试技巧

•打印变量：在代码里加print(变量名)，结果会显示在之前打开的系统控制台里 。

•重载脚本：开发时，修改代码后不需要重启 Blender。在文本编辑器里点击运行脚本按钮即可重新加载 。

8.2 打包与发布

1. 打包为 .zip：

•旧版插件：直接把 .py 文件压缩成 zip。

•新版扩展：把整个文件夹压缩成 zip。

2. 发布：可以在 Github 上分享，或者上传到 Blender 官方的扩展平台。

---

总结

恭喜你，你已经完成了从 0 到 1 的跨越。回顾一下核心要点：

1.结构：记住bl_info + Operator + register三板斧。

2.交互：通过Panel放按钮，通过 Property 存数值。

3.借助AI：这是现代开发者的必备技能，让 AI 帮你生成模板代码和调试错误。

4.版本：Blender4.2以上记得用blender_manifest.toml 。

开始动手写你的第一个插件吧，哪怕只是让立方体动一下，也足以让你感受到创造的乐趣。如果在开发中遇到具体问题，记得随时向 AI 求助!