发布信息

发布时间：2026-02-09
发布平台：微信公众号（草稿箱）
Media ID：IBFk8fgBcWNwp3Epx-oZG7T81jNF19MBzIr4o0PXp5TomhSoXA3Txdqv8HcGOLPf

Vue 3 + Three.js 太复杂？这个组件让 3D 模型接入像用图片一样简单

Vue 项目想加个 3D 模型展示？手动集成 Three.js，光初始化场景、相机、渲染器就要写几十行代码，还要处理模型加载器、渲染循环、窗口缩放...想想就头疼。

今天介绍的 vue-3d-model，把 Three.js 封装成 Vue 组件，让 3D 模型接入像使用 <img> 标签一样简单。三行代码，就能在你的 Vue 3 项目中显示 3D 模型。

2.5k Star，支持 FBX、OBJ、GLTF 等 6 种主流格式。

项目定位

vue-3d-model 是一个为 Vue 3 框架设计的 3D 模型查看器组件库。它将 Three.js 的复杂 API 封装成声明式的 Vue 组件，让开发者能够像使用普通 HTML 标签一样在 Vue 模板中嵌入 3D 模型。

项目基于 Three.js 进行 3D 渲染，使用 TypeScript 开发，提供完整的类型支持。

核心目标：简化 Vue 项目中 3D 模型的集成，降低 Three.js 的使用门槛。

能力边界：适合 3D 模型展示和基础交互（旋转、缩放、平移），不适合需要高度自定义渲染逻辑或复杂 3D 场景的项目。

包含哪些能力

1. 多格式支持

vue-3d-model 支持 6 种主流 3D 模型格式，每种格式对应一个独立组件：

格式	组件名	适用场景
OBJ	`<model-obj>`	通用 3D 模型，广泛使用的格式
FBX	`<model-fbx>`	支持动画的模型，常用于游戏和影视
GLTF/GLB	`<model-gltf>`	现代 Web 标准格式，支持 PBR 材质
JSON	`<model-json>`	Three.js 原生格式
STL	`<model-stl>`	3D 打印常用格式
PLY	`<model-ply>`	点云和网格数据格式

这样设计的原因是，不同格式的模型需要不同的加载器和处理方式。通过独立组件，开发者只需根据模型格式选择对应的组件标签，无需关心底层的加载器实现。

2. 声明式封装

传统的 Three.js 使用方式是命令式的：需要手动创建场景、相机、渲染器，然后通过 API 调用来加载模型和控制渲染。

vue-3d-model 将这些步骤封装成 Vue 组件的 props，开发者只需在模板中声明需要的配置，组件内部会自动完成初始化、加载和渲染。这符合 Vue 的开发习惯，也更容易维护。

3. 内置交互控制

组件内置了常用的 3D 交互功能：

旋转：鼠标拖拽旋转模型
缩放：滚轮缩放视角
平移：按住特定键拖拽平移视角

这些交互基于 Three.js 的 OrbitControls 实现，开发者无需额外配置即可使用。

4. 响应式尺寸

组件支持响应式宽高设置，当容器尺寸变化时，渲染器会自动调整，无需手动监听窗口缩放事件。

安装与使用

安装方式

使用 npm：

npm install vue-3d-model --save

使用 yarn：

yarn add vue-3d-model

使用 pnpm：

pnpm install vue-3d-model

也可以通过 CDN 直接在浏览器中引入：

<script src="//unpkg.com/vue-3d-model"></script>

注意：使用 CDN 方式时，需要先加载 Vue 3。

基础使用示例

假设你的 Vue 项目需要展示一个产品的 3D 模型，模型文件是 OBJ 格式。

步骤1：在组件中导入

<script setup>
import { ModelObj } from 'vue-3d-model'
</script>

步骤2：在模板中使用

<template>
  <model-obj
    src="/path/to/your/model.obj"
    :width="800"
    :height="600"
  />
</template>

步骤3：运行项目

就这样，你的页面上会出现一个可交互的 3D 模型。用户可以用鼠标拖拽旋转、滚轮缩放。

不同格式的使用方式

如果你的模型是其他格式，只需替换组件名：

GLTF 格式（推荐用于 Web）：

<template>
  <model-gltf
    src="/models/scene.gltf"
    :width="800"
    :height="600"
  />
</template>

FBX 格式（适合带动画的模型）：

<template>
  <model-fbx
    src="/models/character.fbx"
    :width="800"
    :height="600"
  />
</template>

STL 格式（3D 打印模型）：

<template>
  <model-stl
    src="/models/part.stl"
    :width="800"
    :height="600"
  />
</template>

配置选项

组件支持通过 props 配置渲染参数：

配置项	类型	说明	默认值
`src`	String	模型文件路径（必填）	-
`width`	Number	渲染区域宽度	容器宽度
`height`	Number	渲染区域高度	容器高度
`backgroundColor`	String	背景颜色	`#ffffff`
`rotation`	Object	模型初始旋转角度	`{x:0, y:0, z:0}`
`cameraPosition`	Object	相机位置	自动计算
`controlsOptions`	Object	交互控制配置	默认启用旋转和缩放
`lights`	Array	灯光设置	默认环境光+方向光

示例：自定义背景色和初始角度

<template>
  <model-obj
    src="/models/product.obj"
    :width="800"
    :height="600"
    backgroundColor="#f0f0f0"
    :rotation="{ x: 0, y: Math.PI / 4, z: 0 }"
  />
</template>

与手动集成的差异

传统的 Three.js 集成方式需要手动初始化场景、相机、渲染器，编写模型加载逻辑，设置灯光和交互控制，维护渲染循环，处理窗口缩放事件，还要在组件销毁时清理资源。完整实现下来，通常需要 60-70 行代码，代码分散在生命周期的多个钩子中，维护成本较高。

使用 vue-3d-model，同样的功能只需要：

<template>
  <model-obj
    src="/path/to/model.obj"
    :width="800"
    :height="600"
  />
</template>

3 行代码，场景初始化、模型加载、渲染循环、交互控制、窗口缩放、资源清理，全部自动处理。代码集中在模板中，清晰易懂，符合 Vue 的声明式开发风格。

适用场景分析

适合使用 vue-3d-model 的场景：

产品展示页面（电商、官网）
建筑/室内设计预览
3D 模型在线查看器
教育演示（生物、化学模型）
简单的 3D 可视化

这些场景的共同特点是：需要展示 3D 模型，但不需要复杂的自定义渲染逻辑或高度定制的交互。

不适合使用 vue-3d-model 的场景：

需要自定义着色器（Shader）的项目
需要复杂粒子系统或后期处理的场景
Web 3D 游戏开发
需要精细控制渲染流程的应用

在这些场景中，直接使用 Three.js 会更灵活，能够实现更精细的控制。

写在最后

vue-3d-model 将 Three.js 的复杂性封装成 Vue 组件，让 3D 模型接入像使用图片标签一样简单。如果你的 Vue 项目需要展示 3D 模型，但不想深入学习 Three.js 的各种 API，这个组件是个不错的选择。

项目已有 2.5k Star，571 个项目正在使用，社区活跃度不错。支持 Vue 3，如果还在使用 Vue 2，可以切换到项目的 v1 分支。

不过需要注意，这个组件更适合标准化的模型展示场景。如果你的项目需要高度自定义的 3D 场景、复杂的交互逻辑或自定义着色器，直接使用 Three.js 会更灵活。根据项目需求选择合适的方案，才能在开发效率和功能实现之间取得平衡。

项目地址：https://github.com/hujiulong/vue-3d-model (opens in a new tab)