Tegaki打包避坑指南Vite预打包TTF失效的完整诊断与修复方案【免费下载链接】tegakiHandwriting animation for the web. Supports any font or text.项目地址: https://gitcode.com/gh_mirrors/teg/tegakiTegaki 是一个开源的手写动画库Handwriting animation for the web能把任意字体变成逐笔书写的文字动画。但新手在 Vite 开发模式下最常踩的坑就是文字消失、TTF 字体加载失败而报错信息却指向一个根本不存在的文件。本文带你完整诊断这个 Vite 预打包 TTF 失效问题并给出一行配置的修复方案。一、症状识别开发模式下字体静默失效的 3 个信号如果你用 Vite7 及以下版本跑vite dev发现 Tegaki 渲染出现以下现象基本可以锁定是预打包问题文字不可见但可以被鼠标选中或者只在开启showOverlay时才显示轮廓控制台出现Failed to decode downloaded font: …/node_modules/.vite/deps/family.ttf或OTS parsing error: invalid sfntVersion伴随NetworkError: A network error occurred或[tegaki] Failed to load font警告。这些日志看起来像网络问题其实请求根本没打到字体文件——问题出在 Vite 的依赖预打包环节。二、根因诊断esbuild 预打包为什么丢了 TTF要理解故障先看 Tegaki 的字体包是怎么加载字体的。每个字体包如 caveat/bundle.ts都使用 ESM 的 import-attributes 语法引用本地的 TTF 文件import fontUrl from ./caveat-3dc76002.ttf with { type: url };字体文件通过相对路径从 bundle 模块内部引用。而 Vite 7 及以下的开发模式会用 esbuild 预打包器把node_modules里的模块复制到/node_modules/.vite/deps/目录。问题就出在这里✅ JS/TS 模块被复制了❌ 同目录下的.ttf文件被留在原地没有被带过去 bundle 模块里的相对字体 URL 指向了一个空位开发服务器对这类未知请求的默认行为是返回index.html 浏览器尝试把一段 HTML 解析成字体于是解码失败。整条因果链可以概括为预打包复制模块 → TTF 未随行 → 相对 URL 悬空 → 服务器回退返回 HTML → 字体解码失败 → 文字消失修复入口和完整原理说明见官方打包器指南bundlers.mdx。三、一键修复一行 optimizeDeps 配置既然根因是预打包把字体甩在了身后最直接的解法就是让 Tegaki 绕过预打包走 Vite 正常的资源管线那里的 URL 解析是正确的。在vite.config.ts中加一行export default defineConfig({ // ... optimizeDeps: { exclude: [tegaki], }, });参考项目中现成的 Vite 示例配置examples/vite/vite.config.ts。修复后必做的两步步骤原因完全重启 dev serveresbuild 只在启动时对配置做预打包热更新不会重新执行建议删除node_modules/.vite/deps/目录清掉旧的、字体悬空的预打包缓存让 Vite 按新配置重新生成字体加载的底层逻辑在 font.ts 中它通过FontFaceAPI 注册bundle.fontUrl指向的文件。只要这个 URL 重新指向真实的 TTF动画即可恢复——无需改动任何业务代码。四、验证修复正常的渲染应该是什么样重启后文字应逐笔书写出来控制台不再出现字体解码错误。修复后的标准渲染效果如下宽文本自动换行场景Tegaki 支持几乎所有脚本韩文等多语言文字同样受益五、哪些环境不需要修复环境是否需要exclude说明Vite 7 及以下 · dev✅ 需要esbuild 预打包会丢失 TTF 资源Vite 7 及以下 · buildRollup 生产构建❌ 不需要生产构建开箱即用问题只影响vite dev和vite previewVite 8Rolldown 预打包❌ 不需要Rolldown 会自己重写资源 URL加上也不影响Webpack / Parcel / esbuild 构建模式❌ 不需要原生支持with { type: url }语法总结现象dev 模式下文字不可见、控制台报 TTF 解码失败根因Vite 7 及以下的 esbuild 预打包复制了 JS 模块却丢下 TTF 文件相对 URL 悬空后命中index.html回退修复optimizeDeps: { exclude: [tegaki] } 完全重启 dev server影响面仅限 Vite 开发模式生产构建和其他打包器均不受影响。按这套流程操作从诊断到修复通常不到两分钟。祝你的手写动画顺利跑起来 ✍️【免费下载链接】tegakiHandwriting animation for the web. Supports any font or text.项目地址: https://gitcode.com/gh_mirrors/teg/tegaki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考