本文由 AI 在分析 Lumina Studio 当前源码、现有 Wiki 内容及相关操作流程后协助撰写，并已按当前版本进行基础核对。由于软件仍在持续更新，内容可能存在疏漏或与后续版本不一致。如发现不准确之处，或有更清晰的解释、案例与建议，欢迎在本页评论区反馈，或通过 GitHub 提交修订。
SVG 上传失败、白底、破洞和细节异常怎么排查？
如果只想先看答案：先保留原文件副本，再把 SVG 简化成“正确画布 + 封闭路径 + 纯色填充”的 最小版本。 最小版本正常，就把文字、渐变、蒙版等效果逐项加回；最小版本仍然异常，再保留文件 和步骤反馈给 Lumina Studio。
SVG 是一个可以包含路径、文字、位图、滤镜和外部资源的容器，不是“只要扩展名是 .svg 就一定
能直接建模”的保证。浏览器能显示，也不代表其中每一种效果都已经变成可打印的封闭几何。
什么样的 SVG 最容易稳定处理？
作为排查基准，一份简单 SVG 最好具备：
- 正确的
viewBox，画布范围能完整包住图形； - 重要文字已经转换为路径；
- 需要形成实体的轮廓是封闭路径，并使用明确的纯色填充；
- 描边效果已经在设计软件中展开为填充路径；
- 孔洞和复合路径使用正确的填充规则；
- 没有不必要的滤镜、蒙版、剪切、外部字体或远程图片；
- 节点数量与画面复杂度相称，没有大量几乎重合的小碎片。
这不是说 Lumina 只能处理最简单的路径。当前版本可以处理多种 SVG 结构和部分渐变，但复杂功能 越多，设计软件、浏览器、SVG 解析器与最终几何之间出现差异的机会也越多。排查时应先建立一个 简单、可验证的基准。
症状一：SVG 无法上传或上传后没有预览
按下面顺序检查：
- 确认文件是真的 SVG。 不要只把 PNG、JPG 的扩展名改成
.svg；在文本编辑器中应能看到<svg ...>根元素。 - 用浏览器和矢量编辑器分别打开。 两者都打不开时，通常应先修复或重新导出源文件。
- 另存为普通 SVG。 从设计软件重新“另存为”或“导出”，不要直接使用损坏的临时文件、网页 片段或复制不完整的 XML。
- 检查画布尺寸。 至少提供有效
viewBox；宽高不能同时变成 0，内容也不能全部落在画布外。 - 移除外部依赖。 把远程图片、外部字体和链接资源嵌入或转换为本地路径。
- 先做最小测试。 新建一个只有单个彩色矩形的 SVG 上传，确认入口本身正常。
当前转换入口常见支持 JPG、PNG、SVG、WebP 和 HEIC。文件扩展名正确但内部内容损坏时，仍然可能 无法读取。
症状二：透明背景变成整块白色
先分清两种完全不同的“白底”：
这是作品需要的物理底板
透明 SVG 只表示画布背景没有颜色，不表示 3D 模型可以悬空。Lumina 仍可能按照当前设置生成实体 底板，让各个色块成为一个可以打印和拿起的整体。
这种情况下，检查转换页面的底板耗材和高级设置中的“分离底板”。如果需要另一种底板颜色，选择 正确的底板耗材；如果只是希望在切片器中单独处理底板，可以按工作流需要使用分离底板。不要通过 删除所有支撑几何来追求“透明”。
SVG 文件本身含有白色矩形或位图背景
如果白色覆盖了整个画布并且不符合预期，在矢量编辑器的图层/对象面板中检查：
- 是否有与画布同大的白色矩形；
- 是否嵌入了一张带白底的位图；
- 蒙版或剪切区域在导出时是否被烘焙成白色；
- 原本用于预览的背景层是否也被导出了。
删除不需要的背景对象，或保留一份透明 PNG 用高保真模式比较。透明背景与物理底板是两件事， 不要只看最终画面颜色判断来源。
症状三：路径出现破洞、断线、重叠或自交
这类问题通常来自“屏幕外观看起来连着，但几何并没有形成稳定封闭区域”。
断线或区域缺失
- 把需要实体化的开放线条闭合；
- 只有描边、没有填充的线条，先执行“描边转路径”或“扩展描边”；
- 给重要细线留出足够打印宽度，不要让它在目标尺寸下比喷嘴线宽还细；
- 检查图形是否落在
viewBox外或被剪切路径截掉。
孔洞被填实或位置错误
- 检查复合路径的方向和
fill-rule； - 在设计软件中使用布尔“差集”明确制作孔洞；
- 不要用一块白色图形盖在深色图形上假装透明孔洞，除非你本来就希望它成为白色材料；
- 展开编组后确认孔洞与主体属于预期的复合路径。
重叠与自交
- 合并真正应该连成一体的区域；
- 对自交路径执行修复、简化或重新绘制；
- 删除重复路径和肉眼看不见的重合副本；
- 保留一份未破坏原始设计的副本，再对清理版做布尔运算。
Lumina 会尝试修复一部分无效几何，但自动修复可能把自交路径拆成多个多边形，也可能丢弃只剩线段 的部分。源文件本身明确，结果才最可预测。
症状四：渐变、滤镜、蒙版或文字没有按预期保留
渐变
矢量模式最终需要把连续渐变转换为有限的颜色区域和材料配方，因此它不会像显示器一样保持无限 连续变化。当前版本可以处理部分线性和径向渐变，但复杂渐变、叠加透明度和混合效果仍应实际预览。
如果最重要的是原画的视觉渐变，可以同时导出高分辨率透明 PNG，用高保真模式比较；如果最重要的 是几何边界，可以在设计软件中把渐变分段或转换为明确色块。
滤镜、蒙版和剪切
模糊、发光、阴影、复杂蒙版、图案填充和剪切路径在不同解析器中的结果可能不同。可以：
- 把关键外观展开为普通路径和纯色填充；
- 将纯视觉效果固定成透明位图，再用高保真处理；
- 删除只用于编辑器预览、并不需要打印的隐藏对象和滤镜。
大画幅矢量切分对文字、嵌入图片、图案、剪切路径、蒙版和滤镜等结构的限制会更严格；必要时软件 可能改用栅格路径。做大画幅前先用普通尺寸验证源文件。
文字
使用字体名称保存的文字依赖接收环境是否有同一字体，也可能在解析时保持为文字对象而不是封闭 几何。发布或导入前把最终文字转换为路径，并检查字腔孔洞、笔画粗细和目标尺寸。
症状五：位图转成 SVG 后仍有锯齿，甚至更差
自动描摹只能根据现有像素猜轮廓，不能恢复源图里已经不存在的细节。
- 低清 Logo 的锯齿可能被描成弯曲路径；
- JPG 压缩块可能变成大量小色块；
- 照片噪点可能变成成千上万个节点；
- 半透明边缘可能被拆成多层灰边。
简单 Logo 可以清理后重描；照片和复杂插画通常更适合保留位图，用高保真模式处理。模式选择可以 参考 高保真、像素艺术与矢量模式怎么选？。 需要重新走一遍自动描摹、结果对照和发送流程时，参考 从位图生成 SVG，再发送到图像转换。
症状六：文件节点太多，预览卡住或生成很慢
先看文件复杂度，而不是只看文件体积。一个只有几 MB 的 SVG 也可能包含几十万个节点、重复路径和 碎片对象。
可以依次尝试：
- 删除画布外、隐藏和重复对象；
- 合并同色且真正相连的区域；
- 在不破坏轮廓的前提下简化节点；
- 去掉无法打印的小碎片；
- 把复杂滤镜或照片部分改为位图；
- 先缩小到普通尺寸验证，再进入大画幅或批量流程。
不要一次把简化强度拉到最大。过度简化会把眼睛、小字、锐角和孔洞一起删掉。
用最小化文件定位问题
这是区分源文件问题和 Lumina 问题最有效的方法：
- 复制原文件，不要在唯一原稿上直接破坏性修改；
- 删除所有非必要内容，只保留正确
viewBox和一个封闭纯色路径； - 上传并生成预览；
- 如果正常，每次只加回一类内容，例如第二个路径、文字、渐变或蒙版；
- 记录从哪一步开始异常；
- 如果最小文件仍异常，用它作为复现文件反馈。
判断结果：
- 最小文件正常、加回某类效果后异常：优先处理该 SVG 结构或改用高保真；
- 同一原文件在浏览器和编辑器中也异常：先修复源文件；
- 最小文件在其他查看器正常，但 Lumina 稳定复现异常：保留最小文件和具体步骤反馈；
- 只有切片后异常：进入切片器检查对象、喷嘴、线宽和逐层路径，不再停留在 SVG 上传阶段。
反馈问题时应附上什么？
建议提供：
- 能复现问题的最小 SVG，而不是只提供截图；
- 你期望看到的画面截图；
- Lumina Studio 版本、来源类型和建模模式；
- 目标成品尺寸；
- 从上传到异常出现的准确步骤；
- Lumina 预览和切片器预览中最早出现异常的那一张图。
提交前移除文件中的姓名、订单、私人链接和不希望公开的元数据。若原作不能公开，可以重新绘制一个 不含版权素材、但仍能复现问题的简单示例。
常见问题 Q&A
SVG 有透明背景，为什么仍然有底板？
透明画布不等于无需物理支撑。先确认看到的是 Lumina 生成的实体底板，还是 SVG 自带的白色矩形。 前者通过底板耗材和分离底板设置处理；后者应回到源文件删除不需要的背景对象。
浏览器里显示正常，为什么 Lumina 少了一部分？
浏览器可以渲染文字、滤镜、蒙版、嵌入位图等视觉效果，而建模需要得到封闭几何。检查缺失部分是否 仍是文字、描边、剪切或外部资源，并尝试转换为普通路径和填充。
把文字转路径后就一定不会出错吗？
不一定，但会去掉字体依赖。转换后仍要检查字腔孔洞、复合路径方向、笔画宽度和目标打印尺寸。
矢量模式出现白线，应该把所有路径都加粗吗？
先判断白线来自源文件间隙、抗锯齿预览，还是切片后的真实缺口。盲目整体加粗可能堵住孔洞和小字。 可以检查路径是否真正相接，再按实际预览谨慎使用描边或修补。
SVG 太复杂时，是继续简化还是换高保真？
如果主要价值是 Logo、文字和清楚边界，优先保留路径并有选择地简化；如果主要价值是照片、纹理、 阴影和复杂渐变，导出高分辨率透明 PNG，用高保真通常更直接。两种结果都可以按最终尺寸比较。
内容许可
本文原创文字、表格和示意图，除另有说明外，适用 Wiki 的 CC BY-NC-SA 4.0 内容许可。SVG、字体、商标、角色形象和 其他第三方素材的相关权利归各自权利人所有。
SVG 生态和 Lumina Studio 都会继续更新。具体格式兼容性以当前版本的真实导入、预览、生成和切片 结果为准。
提交反馈
反馈会直接发送给 Wiki 维护者，不会在本页公开显示。