这次问题出现在 3D PPT 编辑器里嵌入单模型控制页时：柔和模式下首次新增模型，模型区域会出现整块黑底；切到暗黑模式时又可能变成白底。Three.js 的透明 clearColor、iframe 的 transparent、父容器 background 都已经处理过，现象依然反复。
最终定位到根因后，问题非常集中：iframe 会继承浏览器环境的 color-scheme，父页面和 iframe 的 color-scheme 需要保持一致，透明渲染链路才稳定。
一、问题现象
- 3D PPT 柔和模式下，内嵌模型区域出现黑底。
- 3D PPT 暗黑模式下，内嵌模型区域又可能出现白底。
- 直接访问单模型页时，黑底和白底表现与内嵌场景不一致。
- 删除一整份
style.css后，透明现象暂时恢复。
这个现象说明问题并不只在 Three.js 渲染层，浏览器对文档主题的默认绘制也参与了最终结果。
二、为什么会误判成 Three.js 透明问题
遇到 iframe 黑底时，最先怀疑的通常是下面几项：
| 怀疑点 | 常见处理 |
|---|---|
| Canvas 清屏颜色 | renderer.setClearColor(0x000000, 0) |
| Renderer alpha | new THREE.WebGLRenderer({ alpha: true }) |
| Scene 背景 | scene.background = null |
| DOM 容器背景 | html, body, #app, #viewport { background: transparent } |
| iframe 属性 | allowtransparency 和透明样式 |
这些处理都需要做，但它们解决的是“渲染层主动上色”的问题。当前这次问题来自浏览器对页面主题的默认背景参与绘制，所以只改 Three.js 仍然会出现黑底或白底。
三、根因：父页面和 iframe 的 color-scheme 需要一致
单模型页中曾经有过这样的样式：
:root {
color-scheme: dark;
}这行代码会告诉浏览器：当前文档使用 dark 主题语义。父页面如果处于柔和模式，而 iframe 自己仍声明为 dark，浏览器会为 iframe 文档采用不同的默认主题环境。此时即使我们让 canvas 和容器背景走透明，最终透出来的也可能是浏览器在该 color-scheme 下的默认背景结果。
这次排查的关键结论就是：
父页面 theme = light → iframe color-scheme 也要是 light
父页面 theme = dark → iframe color-scheme 也要是 dark只要两边一致，透明链路就稳定；两边不一致，透明区域就容易被浏览器主题环境“补色”。
四、正确修复方案
修复方案分成两步：
1. 父页面显式把 theme 传给 iframe
export function buildSceneviewModelUrl(source = '', options = {}) {
const url = new URL(SCENEVIEW_MODEL_BASE)
url.searchParams.set('url', normalized)
url.searchParams.set('opacity', '1')
url.searchParams.set('transparent', '1')
if (options.theme) {
url.searchParams.set('theme', options.theme)
}
return url.toString()
}这样 3D PPT 在暗黑模式下会传 theme=dark，柔和模式下会传 theme=light。
2. iframe 页面按 theme 设置 color-scheme
<script>
const sceneParams = new URLSearchParams(window.location.search)
const sceneTheme = sceneParams.get('theme')
if (sceneTheme === 'dark' || sceneTheme === 'light') {
document.documentElement.dataset.theme = sceneTheme
}
</script>:root {
color-scheme: dark;
}
html[data-theme='light'] {
color-scheme: light;
}
html[data-theme='dark'] {
color-scheme: dark;
}这套方案让 iframe 的文档主题始终跟父页面同向，透明渲染和浏览器默认主题环境保持一致。
五、为什么“删掉 style.css 就透明了”
删掉整份样式后，最核心的变化其实是 color-scheme 消失了。浏览器不再收到一个强制 dark 的主题声明，iframe 会回到更接近父页面的默认环境，所以透明看起来恢复了。
真正起作用的不是“样式文件越少越透明”，而是“浏览器主题语义恢复一致”。
六、排查这类问题的顺序
以后遇到 iframe 透明异常，我建议按这个顺序排查：
- 确认 Three.js renderer 是否开启
alpha，setClearAlpha(0)是否生效。 - 确认
scene.background、canvas、html/body/#app是否都是真透明。 - 确认 loading mask、面板、占位层没有覆盖透明区域。
- 确认父页面和 iframe 的
theme是否同步。 - 确认 iframe 内文档的
color-scheme与父页面一致。
前三步检查渲染层，后两步检查浏览器主题层。两层都一致，透明结果才稳定。
七、结论
这次 3D PPT 模型 iframe 黑底/白底问题的本质是浏览器主题环境参与了透明区域的最终呈现。父页面和 iframe 的 color-scheme 一致时，透明背景才能稳定工作。
对于带主题切换的嵌入式页面，稳定方案就是：父页面传 theme，iframe 用同一个 theme 驱动 color-scheme，再叠加 Three.js 的透明渲染设置。