这份 Fabric.js 问题排查指南汇总了大家最常遇到的问题,按通常出现的顺序排列。
撤销没有记录我的改动
Fabric.js 只在鼠标交互、添加和删除对象、文本编辑时触发事件。你的代码用 object.set() 或 canvas.bringObjectForward() 做的改动不会触发任何事件。把它们包起来:
engine.transaction("Recolor", () => shape.set("fill", "teal"));撤销后对象引用失效了
撤销和重做会重建改动过的对象,所以它们是 id 不变的新实例。保存 id,再用 engine.getObjectById(id) 查找对象。
加载后自定义属性丢了
用普通的 toJSON 和 loadFromJSON 时,Fabric.js 只保存它认识的属性。把类和它的自定义属性注册一下:
engine.registerObject({ fabricClass: Sticker, properties: ["label"] });加载以 UNKNOWN_OBJECT_TYPE 失败
文档里有当前页面没注册的类。通过 customObjects 传入,或在加载前调用 registerObject。这个类需要一个和保存的 type 一致的静态 type。在普通 Fabric.js 里,同样的问题会表现为 klass.fromObject is not a function。
打包结果里有两份 Fabric.js
在一份里注册的类另一份不认识,加载会以 UNKNOWN_OBJECT_TYPE 失败。请确认只安装了一份 fabric。在 Vite 里使用链接的包时,加上 resolve: { dedupe: ["fabric"] }。
加载以 MISSING_ASSETS 失败
error.missingAssets 列出了每张没加载成功的图片。用 assets.resolveUrl 修正地址,用 assets.replaceMissingImage 提供替代图片,或者之后调用 engine.replaceImage(oldUrl, newUrl)。每一项都有 failure.reason(NOT_FOUND、HTTP_ERROR、CORS、NETWORK、TIMEOUT 或 DECODE),说明该修什么;服务器慢时,调大 assets.imageTimeout。
重新打开后文字显示不一样
创建文字时字体还没加载,所以 Fabric.js 用后备字体测量了它。在 assets.loadFont 里加载网络字体,并留意 FONT_UNAVAILABLE 警告。
导出时画布被污染
有一张来自其他网站的图片没用 CORS 加载,浏览器因此拦截 PNG、JPEG 和 WebP 导出。从返回 Access-Control-Allow-Origin 的服务器,用 crossOrigin: "anonymous" 加载它。运行 engine.preflightExport({ format }),可以在用户点击导出前提示这个问题。
SVG 里的曲线文字和画布不一样
检查文字是不是在开启了对象缓存的编组里。这时 Fabric.js 会在画布上裁掉高出路径的字母,而 SVG 会完整显示它们;给这个编组设置 objectCaching: false。缺少的字体用 svg.embedFonts 传入。详见 SVG 导出。
SVG 在 Illustrator 或浏览器里打不开
Fabric.js 6 和 7 会把含空格的路径文字写成无效的 XML。engine.export({ format: "svg" }) 会修复它,直接调用 canvas.toSVG() 则不会。
在别处打开 SVG 时图片不见了
导出时设置 svg: { embedImages: true }。来自其他网站、没有 CORS 的图片会保留为链接,并给出 IMAGE_NOT_EMBEDDED 警告。
导入的 SVG 位置不对
util.groupSVGElements 按绘制的内容确定编组大小,所以 viewBox 之外的元素会让整体移动。改用 engine.importSvg(svg),见 SVG 导入。
PDF 导出以 PDF_UNAVAILABLE 失败
用 npm install jspdf svg2pdf.js 安装可选的包。PDF 导出也需要浏览器。
PDF 里的文字是图片,或字体不对
在 fonts 里为每个字体族传入 TrueType(.ttf)文件,每种字重和样式一个。WOFF 和 WOFF2 文件会以 PDF_FAILED 被拒绝。详见 PDF 导出。
批量渲染时内存耗尽
用 renderDocuments 代替每份文档一个画布,保持较低的 concurrency,每个结果到达后就上传。详见批量渲染。
只开一个标签页也报 SAVE_CONFLICT
你的适配器没有返回新的修订号。在 saveDocument 里返回 { revision },或者保存 document.revision。
恢复提示一直不出现
传入 recovery: { store: createIndexedDbRecovery() }。只有存在未保存改动时才会写副本;隐私浏览模式可能在关闭窗口时清空存储。
加载时报 LOAD_CONFLICT
文档打开期间画布被修改了,这些修改被保留了下来。先询问用户,再用 discardUnsavedChanges: true 重新加载,见 保存和加载。
Textbox 比设定的宽度更宽
Fabric 会把 Textbox 撑到最长单词的宽度。改用 BoundedTextbox,见 文本框宽度。
在 Android 上输入时字母或样式位置错误
在开始编辑之前调用 attachMobileTextInput(canvas),见 手机上的文字输入。
有几千个对象时拖动很慢
用 enableDirtyRegionRendering(canvas) 开启脏区域渲染,见 渲染大量对象。
应用滤镜时页面卡住
用 createFilterWorker() 运行滤镜,见 图片滤镜。
React:开发环境里有两个引擎
StrictMode 会把 effect 挂载两次。useDocumentEngine 会销毁第一个引擎,所以只有一个在运行。始终使用 hook 返回的引擎。
Vue:加载后画布不渲染
Vue 把 Fabric.js 画布包成了响应式代理。把它放在 shallowRef 里,或者传入 toRaw(canvas)。详见 Vue。
Next.js:"window is not defined"
Fabric.js 在服务端运行了。用 dynamic(() => import("./editor"), { ssr: false }) 加载编辑器。详见 Next.js。
如果这份 Fabric.js 问题排查清单没有覆盖你的问题,请带上错误 code、Fabric.js 版本和浏览器信息,提交一个 issue。