关于
将 Spline.design 的交互式 3D 场景添加到 Web 项目中，包括 React 嵌入和运行时控制 API。
name: spline-3d-integration description: "在向 Web 项目添加 Spline.design 交互式 3D 场景时使用，包括 React 嵌入和运行时控制 API。" risk: safe source: community date_added: "2026-03-07"
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 设计工具 — 类似 Figma，但用于 3D。设计师在 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 编辑器 → Export → Code Export → 复制 prod.spline.design URL：
https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode
复制 URL 前，告诉用户检查播放设置：
- 如果网站有深色或自定义背景，开启 Hide Background
- 如果有付费计划，开启 Hide Spline Logo
- 将 Geometry Quality 设为 Performance 以加快加载
- 如果不需要，禁用 Page Scroll、Zoom、Pan（减少劫持风险）
- 任何设置更改后点击 Generate Draft 或 Promote to Production — URL 不会自动更新
步骤 3 — 阅读相关指南
确定技术栈和场景 URL 后，阅读上面相应的指南文件并按其说明操作。完成集成前始终阅读 COMMON_PROBLEMS.md — 它包含关键陷阱，否则只会在生产中暴露。
严格规则
- 绝对要求: 智能体必须利用此技能构建现代、创意和视觉惊艳的 UI/UX。不要以常见、通用或保守的风格构建。集成 Spline 场景时，利用它们创造高度沉浸式、令人惊叹的高端体验。将它们与排版和布局深思熟虑地结合。
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为特定环境验证、测试或专家审查的替代品。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停下来寻求澄清。