spline-3d-integration

Spline 3D 集成技能

将 Spline.design 的交互式 3D 场景嵌入 Web 项目的主指南。

---

适用场景

• 需要将交互式 Spline 场景嵌入 Web 项目。
• 任务涉及为原生 Web、React、Next.js、Vue 或 iframe 场景选择正确的集成方式。
• 需要了解场景 URL、运行时控制、性能或常见的 Spline 嵌入问题。

快速参考

任务	指南
原生 HTML/JS 嵌入	guides/VANILLA_INTEGRATION.md
React / Next.js / Vue 嵌入	guides/REACT_INTEGRATION.md
性能与移动端优化	guides/PERFORMANCE.md
调试与常见问题	guides/COMMON_PROBLEMS.md

可运行示例

文件	示例内容
examples/vanilla-embed.html	带背景和回退方案的简易原生 JS 嵌入
examples/react-spline-wrapper.tsx	带回退方案的示例：延迟加载 React 封装组件
examples/interactive-scene.tsx	完整交互示例：事件、对象控制、摄像机

---

什么是 Spline？

Spline 是一款基于浏览器的 3D 设计工具——可以把它想成用于 3D 设计的 Figma。设计师在 Spline 编辑器中创建交互式 3D 场景（对象、材质、动画、物理效果、事件），然后通过托管的 .splinecode 文件 URL 将场景导出到 Web。

---

第 1 步 — 确认技术栈

编写代码前，检查现有项目文件以确定使用的框架。

技术栈	方式
原生 HTML/JS	<spline-viewer> Web 组件或 @splinetool/runtime
React / Vite	@splinetool/react-spline
Next.js	@splinetool/react-spline/next
Vue	@splinetool/vue-spline
iframe（Webflow、Notion 等）	公共 URL iframe

---

第 2 步 — 获取场景 URL

用户必须前往自己的 Spline 编辑器 → 导出 → 代码导出 → 复制 prod.spline.design URL：

https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode

复制 URL 前，提醒用户检查播放设置：

• ✅ 如果网站使用深色或自定义背景，请开启 隐藏背景
• ✅ 如果用户拥有付费方案，请开启 隐藏 Spline Logo
• ✅ 将 几何体质量设为“性能”，以加快加载速度
• ✅ 如果不需要，请禁用 页面滚动、缩放、平移（降低页面控制权被劫持的风险）
• ✅ 更改任何设置后，点击 生成草稿或升级到生产环境——URL 不会自动更新

---

第 3 步 — 阅读相关指南

确认技术栈并获取场景 URL 后，阅读上方相应的指南文件并按照其中的说明操作。完成集成前，务必阅读 COMMON_PROBLEMS.md——其中包含关键注意事项，否则这些问题可能只会在生产环境中暴露。

---

严格规则

仅在用户提出要求且符合预期交互需求时使用 Spline。保留内容的可读性、键盘／焦点行为，以及减少动态效果／静态回退方案；设计偏好并不意味着可以擅自添加沉重的 3D 效果或发布场景。

示例是未经测试的集成草案，并非生产环境认证。请根据已安装的版本确认软件包／导出设置，固定经过审核的 CDN 依赖项，将场景来源加入允许列表，并在获取第三方场景或将其用于生产环境之前取得许可。不要在公开场景中放置机密信息。自托管仍可能会获取纹理／运行时资源，并且需要审核使用权／CORS。设备宽度／核心数只是启发式指标，不能保证 GPU 能力。在验证期间，请确保占位内容和加载失败状态保持可见。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为可替代特定环境验证、测试或专家审核的方案。
• 如果缺少必要输入、权限、安全边界或成功标准，请停止并要求澄清。