如何在Vite项目中通过npm引入ModelViewer并渲染3D模型？

1. 安装依赖 #

首先在项目根目录执行命令安装官方包：

npm install @google/model-viewer
# 也可使用yarn/pnpm
# yarn add @google/model-viewer
# pnpm add @google/model-viewer

2. 配置Vite（关键：处理自定义元素） #

model-viewer属于自定义HTML元素，Vite默认的编译优化可能会干扰其注册流程，需要在vite.config.js中添加排除配置：

import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    // 排除model-viewer，避免Vite误处理自定义元素
    exclude: ['@google/model-viewer']
  }
});

3. 引入库并创建实例 #

在业务JS文件（比如main.js或组件脚本）中，先导入库完成自定义元素注册，再创建实例：

// 导入model-viewer，自动完成自定义元素注册
import '@google/model-viewer';

// 创建model-viewer实例
const modelViewer = document.createElement('model-viewer');

4. 配置属性并插入DOM #

给实例设置必要属性后，插入到页面指定位置：

// 配置3D模型路径（遵循Vite资源规则）
// 方式1：模型放在public文件夹，直接用根路径
modelViewer.src = '/my-model.glb';
// 方式2：模型在src/assets下，先导入再赋值
// import modelUrl from './assets/my-model.glb';
// modelViewer.src = modelUrl;

// 配置其他属性，和CDN使用方式一致
modelViewer.alt = '展示用3D模型';
modelViewer.setAttribute('auto-rotate', true);
modelViewer.setAttribute('camera-controls', true);
modelViewer.style.width = '800px';
modelViewer.style.height = '600px';

// 插入到指定容器（比如页面中id为model-container的元素）
const container = document.getElementById('model-container');
container.appendChild(modelViewer);

// 也可直接插入到body
// document.body.appendChild(modelViewer);

注意事项 #

• 路径规则：Vite中public文件夹下的资源可通过根路径直接访问，src内的资源需通过import引入获取打包后的正确路径。
• 属性配置：CDN方式支持的所有属性（如environment-image、shadow-intensity等），都可通过setAttribute或直接DOM属性赋值来配置。
• 框架适配：如果使用Vue/React等框架，需确保框架不拦截自定义元素渲染，比如Vue可在配置中添加vue: { customElement: true }。

内容的提问来源于stack exchange，提问作者Nicoli