Tolaria 离线优先启动：用 Fontsource 内置字体资产取代渲染阻塞的 Google Fonts-平芜编程栈

Tolaria 离线优先启动：用 Fontsource 内置字体资产取代渲染阻塞的 Google Fonts

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

导读

本篇围绕 Tolaria（基于 Tauri + React 的 Markdown 知识库桌面应用）的架构决策记录 docs/adr/0176-bundled-font-assets-for-offline-startup.md，深入解析其如何通过 Fontsource 把 Inter、IBM Plex Mono、JetBrains Mono 三套字体随渲染器一起打包，从而让启动文档（HTML bootstrap）不再发出任何外部字体请求。读完本文，你将理解"离线优先契约"下字体加载的完整链路：从 package.json 依赖、src/main.tsx的 CSS 导入，到 Tauri 内容安全策略（CSP）的收紧，以及对应的单元测试如何守护这一约束。

背景与问题：一条阻塞首帧渲染的外部字体请求

Tolaria 的启动文档（index.html）自带一套完整的"启动壳"（startup shell fallback）内联样式，可以在 React chunk 加载前就绘制出侧边栏、列表和编辑区的骨架外观（对应组件为 StartupShellFallback.tsx，以及 index.html 中#tolaria-boot-shell的静态结构与内联 CSS）。

在 ADR 0176 之前，这个 HTML bootstrap 通过一张渲染阻塞（render-blocking）的 Google Fonts 样式表加载 Inter、IBM Plex Mono 和 JetBrains Mono。渲染阻塞的含义是：WebView 必须等样式表请求完成并解析后，才允许执行首次绘制（first paint）。对于一款明确承诺"离线优先"的桌面应用，这会带来三类现实场景的启动失败：

完全离线：无网络时请求挂起直至超时；
隔离网络（air-gapped）：企业内网、机密环境无法访问外网字体 CDN；
防火墙拦截：请求被拦截后虽然会快速失败，但失败之前窗口已经出现明显空白等待。

无论哪种情况，字体端点失败都可能延迟 Tolaria 启动壳的首次绘制，破坏产品的离线优先契约——这与项目在 docs/adr/0060-network-aware-ui-gating-for-remote-features.md、docs/adr/0146-cached-main-window-startup-with-empty-reload-recovery.md 等一系列决策中强调的"远程特性按网络感知门控、本地体验不依赖网络"是一致的。

ADR 也评估了替代方案：退回系统字体（system-font fallbacks）。该方案确实能彻底移除网络依赖，但代价是排版在不同机器之间、以及同一台机器的在线/离线会话之间都会变化——这会让笔记应用的阅读体验不可预测。于是该方案被否决。

决策：通过 Fontsource 包内置字体资产

ADR 0176 的最终决策是：

通过 Fontsource 包把既有字体家族随渲染器一起内置；从src/main.tsx加载变量版 Inter 和 JetBrains Mono 的权重资源，以及 IBM Plex Mono 的 400、500、600 权重；同时把 Google Fonts 从 HTML bootstrap 和 Tauri 的两份内容安全策略中移除。

"两份 CSP"指的是 tauri.conf.json 中的security.csp（生产）与security.devCsp（开发）。src-tauri/tauri.dev.conf.json仅覆盖少量开发字段，因此生产与开发两份策略都收敛在同一声明文件中。

依赖清单：三个 Fontsource 包

在 package.json 的dependencies中，三个字体包版本如下：

"@fontsource-variable/inter": "^5.3.0", "@fontsource-variable/jetbrains-mono": "^5.3.0", "@fontsource/ibm-plex-mono": "^5.3.0"

这里的关键区别是包名中的variable：Inter 与 JetBrains Mono 走的是变量字体路线，只引入wght.css一个样式文件，便可覆盖任意字重；IBM Plex Mono 则按固定字重拆分为 400/500/600 三个样式文件。

加载入口：src/main.tsx

字体样式在渲染器模块入口 src/main.tsx 的顶部导入，位于 React 根组件创建之前：

import '@fontsource-variable/inter/wght.css' import '@fontsource-variable/jetbrains-mono/wght.css' import '@fontsource/ibm-plex-mono/400.css' import '@fontsource/ibm-plex-mono/500.css' import '@fontsource/ibm-plex-mono/600.css'

src/main.tsx是 Vite 构建的模块入口（见 index.html 的<script type="module" src="/src/main.tsx">），也是 Tauri 生产构建beforeBuildCommand: pnpm build && pnpm bundle-mcp && pnpm agent-docs（见 tauri.conf.json）所打包的渲染器根。把字体导入放在这里，意味着字体资产会随渲染器一起进入 Vite 产物。

字体在 UI 中的真实引用

内置字体不是摆设，它们在界面层有明确引用点，这解释了为什么必须保证三套字体同时可用：

字体家族	加载形式	主要 UI 引用位置
Inter	变量字体（全字重）	全局默认字体 src/index.css、编辑器主题变量 src/theme.json 中的`editor.fontFamily`
IBM Plex Mono	固定 400 / 500 / 600	AI 聊天 Markdown 中的代码样式 src/index.css、编辑器的行内代码字体变量（`--inline-styles-code-font-family`，见 EditorTheme.css）
JetBrains Mono	变量字体（全字重）	CodeMirror 代码编辑视图的等宽字体 src/hooks/useCodeMirror.ts

具体到编辑器：BlockNote 富文本编辑区的字体由 CSS 自定义属性驱动，.bn-editor { font-family: var(--editor-font-family); }（EditorTheme.css），而--editor-font-family的值来自 theme.json 经 useTheme.ts 的flattenTheme扁平化转换（camelCase → kebab-case）后注入。也就是说，Inter 变量字体的可用性直接影响编辑器的最终排版效果。

构建链：WOFF2 资产如何进入应用包

从源码结构可以推断出完整的字体资产路径：

src/main.tsx导入@fontsource-*包的 CSS；
这些 CSS 内部以url(...)引用 WOFF2 字体文件；
Vite 在pnpm build阶段将这些 WOFF2 作为静态资源（asset）打包进dist/assets/；
Tauri 的build.frontendDist指向../dist（tauri.conf.json），产物随应用一起分发。

由于构建目标按平台区分（非 Windows 为safari13、Windows 为chrome105，见 vite.config.ts），字体格式选择 WOFF2 也兼顾了 WebKit 与 Chromium 两类 WebView 的兼容性。

CSP 收紧：不再向 Google Fonts 开放

ADR 的第二个动作是从两份内容安全策略中移除 Google Fonts。当前 tauri.conf.json 中与字体、样式相关的策略为：

"csp": { "style-src": "'self' 'unsafe-inline'", "style-src-elem": "'self' 'unsafe-inline'", "style-src-attr": "'unsafe-inline'", "font-src": "'self' data:" }

要点分析：

font-src "'self' data:"：字体只能从应用自身来源（'self'，即打包进dist的 WOFF2）或data:URI 加载，不再包含https://fonts.gstatic.com；
style-src系列保持'unsafe-inline'，因为 Tauri 运行时代码与 React 内联样式需要动态样式注入——这是由 src/utils/tauriCsp.test.ts 单独守护的策略约束；
生产script-src仍保持严格（不含'unsafe-inline'、不含'unsafe-eval'，仅含'wasm-unsafe-eval'），与字体收紧一起体现了"最小权限"的整体安全姿态（关联决策见 docs/adr/0154-sandboxed-fenced-html-blocks.md）。

devCsp虽然因 Vite React Refresh 需要而放开了script-src 'unsafe-inline' 'unsafe-eval'与本地 WebSocket，但同样不含任何fonts.googleapis.com/fonts.gstatic.com端点——开发与生产在字体策略上保持了一致。

测试守护：让"离线字体加载"成为可验证的回归约束

这一决策不是一次性修改，而是被固化进了测试。在 src/utils/tauriCsp.test.ts 中有一个专门的用例keeps startup font loading local and network independent，它逐项断言：

const hasRemoteFontEndpoint = /https:\/\/fonts\.(?:googleapis|gstatic)\.com/.test(appDocumentSource) expect(hasRemoteFontEndpoint).toBe(false) // index.html 无远程字体端点 expect(packageJson.dependencies).toMatchObject({ '@fontsource-variable/inter': expect.any(String), '@fontsource-variable/jetbrains-mono': expect.any(String), '@fontsource/ibm-plex-mono': expect.any(String), }) // 三个包必须存在 expect(mainEntry).toContain("import '@fontsource-variable/inter/wght.css'") expect(mainEntry).toContain("import '@fontsource-variable/jetbrains-mono/wght.css'") expect(mainEntry).toContain("import '@fontsource/ibm-plex-mono/600.css'") expect(csp['style-src']).not.toContain('fonts.googleapis.com') // 生产 CSP 收紧 expect(csp['style-src-elem']).not.toContain('fonts.googleapis.com') expect(csp['font-src']).not.toContain('fonts.gstatic.com') expect(devCsp).not.toMatch(/https:\/\/fonts\.(?:googleapis|gstatic)\.com/) // 开发 CSP 同步收紧

该测试直接读取index.html、src/main.tsx、package.json与src-tauri/tauri.conf.json的真实内容做静态断言。这意味着：任何后续 PR 若重新引入 Google Fonts 链接、删除字体包或把导入挪走，CI 都会立刻失败。这是一种"以测试固化架构决策"的实践，与项目中 docs/adr/0051-shared-shortcut-manifest-for-testable-routing.md 等"决策可测试化"的思路一脉相承。

后果与权衡

收益

启动文档零外部请求：HTML bootstrap 中没有任何外部字体或样式表请求，字体端点失败不可能再延迟首帧绘制；离线、隔离网络与防火墙拦截场景下的启动行为与在线一致；
排版一致性：在线/离线、不同机器之间使用完全相同的字体资产，不再因系统字体差异而漂移；
CSP 面缩小：生产 CSP 不再为 Google Fonts 开放style-src/font-src来源，减少了对外部 CDN 的信任面。

代价

应用包体积增加：三套字体（含变量字体权重与 WOFF2 静态资源）随渲染器进入dist，直接增大安装包体积——这是"离线优先"换取确定性的合理成本；
依赖维护义务：Fontsource 包需要与常规依赖一起接受版本升级与漏洞维护（当前锁定在^5.3.0系列）。

如何验证当前仓库的落地状态

在仓库中你可以通过三条路径快速核验这一决策的完整性：

检查入口导入：grep "fontsource" src/main.tsx，应看到 5 行 CSS 导入（2 个变量包 + 3 个固定字重）；
检查策略：grep -i "googleapis\|gstatic" src-tauri/tauri.conf.json index.html，应无任何匹配；
跑测试：执行pnpm test或直接运行npx vitest run src/utils/tauriCsp.test.ts，其中keeps startup font loading local and network independent用例会完整校验上述约束。

构建后（pnpm build）可在dist/assets/中看到被打包的.woff2字体文件；pnpm tauri build生成的桌面安装包将把这些资产随渲染器一起分发，从而在完全断网的环境下也能呈现与在线一致的排版。

<输出文章>