Fudoki 架构揭秘：一个纯前端日语分词 PWA 的技术栈全解

【免费下载链接】fudokiAn interactive Japanese text analysis and speech synthesis web app项目地址: https://gitcode.com/gh_mirrors/fu/fudoki

Fudoki（フドキ）是一款开源日语分词 PWA，它把 Kuromoji.js 形态素解析、Kuroshiro 读音转换、JMdict 词典和 Web Speech API 语音合成全部装进浏览器，不需要任何后端即可完成"分词 → 词性标注 → 假名/罗马音 → 词典释义 → 语音朗读"的完整链路。这篇文章将带你拆解这个纯前端日语分词工具的技术栈与架构设计，看看一个数据密集型日语学习应用，如何用纯静态资源实现接近原生应用的体验。

Fudoki 是什么？一款让日语"结构可视化"的网页工具

Fudoki 的名字致敬日本奈良时代的古代地志《风土记》——"风土"是语言的气息与肌理，"记"是记录。这个日语分词工具做的正是"记录语言的风土"：把一句话拆解成一个个词语，标注词性、假名和罗马音，再通过语音朗读还原出句子的节奏。

核心功能一览：

• 📝日语分词分析：分词、词性、假名、罗马音一键展示
• 🗣️日语 TTS 朗读：按单词 / 按行 / 全文播放，语速 0.5–2.0 可调
• 📖词典联动：点击词卡即可查看 JMdict 释义与例句
• 📄Markdown 编辑器：内置 EasyMDE，写作与分析两不误
• 🌐三语界面：中文 / 日语 / 英语一键切换

词性颜色标识，一眼看懂句子结构

核心分词引擎：Kuromoji.js 如何实现纯前端日语分词

整个应用的心脏是 static/segmenter.js 中的JapaneseSegmenter模块。它基于Kuromoji.js（Java 分词器 Kuromoji 的 JavaScript 移植版）完成形态素解析，配合Kuroshiro和KuromojiAnalyzer输出假名与罗马音。

有意思的是，这个纯前端分词方案其实是"去后端化"的产物——它替换了原来 Python 后端的 SudachiPy 功能，把分词词典（base.dat.gz、cc.dat.gz等二进制词典文件）直接放在 static/libs/dict/ 下，由浏览器动态加载。初始化失败时还有一套简化分词兜底逻辑，保证极端环境下应用不会白屏。

离线词典：JMdict 按需分片的三层缓存设计

词典是日语分词工具里最"重"的部分。原始 JMdict 全量数据动辄上百 MB，直接加载会让网页卡死。Fudoki 在 static/libs/dict/dictionary-service.js 里做了一个漂亮的架构决策：按词条首音切成约 75 个分片（dict_あ.json、dict_い.json…）。

查询链路是这样设计的：

1. 全局索引dict_index.json提供 O(1) 定位（headword → 分片名）
2. 首次查询只拉取单个分片（约 1–2MB），而非全量词典
3. 分片数据三层缓存：内存 LRU → IndexedDB 持久化 → Service Worker Cache

配合 ETag 条件请求，离线也能查词；例句分片（examples/ex_*.json）同样按需懒加载，总量约 5.5MB，全缓存无压力。这个设计把首查网络量从 109MB 降到了索引 + 单分片级别。

语音合成：Web Speech API 驱动的日语朗读模块

朗读功能由 static/js/tts.js 提供语音列表与音色绑定，真正的播放状态机（暂停 / 继续 / 停止 / 断点续播）则收敛在 static/main-js.js 的 TTS 引擎区——刻意保持"单一播放状态"，避免历史上出现过的状态分裂 Bug。

实用细节很贴心：

• 🎚️ 播放中改语速或音色，会先暂停再在当前位置附近按新设置续播
• ⏸️ 暂停 / 继续是独立按钮，播放时按钮自动切换为"停止"图标
• 🔁 支持单句循环播放，适合跟读练习
• 📥 朗读设置持久化到 localStorage（统一fudoki:命名空间）

PWA 离线能力：从 Manifest 到 Service Worker 的缓存策略

作为一款日语分词 PWA，离线可用性是标配。manifest.json 声明了 standalone 独立窗口模式与 192/512 双尺寸图标；service-worker.js 实现了两套缓存策略：

• 导航请求走网络优先，失败时回退到缓存首页（离线也能打开应用）
• 静态资源走缓存优先，后台静默刷新

缓存名采用fudoki-cache-vN版本号管理，每次发版递增版本号，activate 阶段自动清理旧缓存，避免"缓存地狱"。首屏还内置了缓存清理脚本（?clear=1），一键重置所有 localStorage、IndexedDB 与 SW 缓存。

Markdown 编辑器与多文档管理：写作工具的完整拼图

Fudoki 不止是分词工具，它还内置了EasyMDEMarkdown 编辑器，替换了普通 textarea：实时预览、全屏写作、语法高亮一应俱全，且分词分析对 Markdown 内容同样生效。搭配多文档管理（static/main-js.js 中的文档列表与文件夹系统）、自动保存、文档搜索，它已经是一个够用的日语学习笔记工作台。

移动端适配与三语国际化：一次编写，处处可用

移动端体验经过专门的走查优化（见 docs/mobile-audit/AUDIT.md 与 docs/mobile-audit/LIGHTHOUSE.md）：

• 📱 底部常驻 TTS 迷你控制条，滚动页面也能随时朗读
• 🗂️ 抽屉式文档列表，支持下拉刷新与左右滑动切换文档
• ⌨️ 触控目标全部放大到 44px 以上，适配刘海屏 safe-area

国际化方面，static/js/i18n.js 提供中 / 日 / 英三语切换，导航栏还贴心地放了国旗按钮（static/flags/）。主题色通过 static/styles.css 的 CSS 变量统一管理，暗色模式一键切换。

如何本地运行这个日语分词工具

想亲身体验？克隆项目后一条命令即可启动：

git clone https://gitcode.com/gh_mirrors/fu/fudoki cd fudoki && python3 -m http.server 8000

打开http://localhost:8000，输入一段日语，点击分析，就能看到分词、词性、假名、罗马音逐层展开，再点播放听整句朗读——全程零安装、零后端，所有数据都在浏览器本地完成。

总结：纯前端日语分词 PWA 的架构启示

回看 Fudoki 的技术栈全解，最值得借鉴的架构思想有三点：把重后端能力（分词、词典）降级为浏览器本地计算，用按需分片 + 三层缓存驯服海量词典数据，再用Service Worker + 版本化缓存保证离线可用。对于想构建数据密集型纯前端应用的开发者来说，这份日语分词 PWA 的代码就是一份绝佳的实战范本。

【免费下载链接】fudokiAn interactive Japanese text analysis and speech synthesis web app项目地址: https://gitcode.com/gh_mirrors/fu/fudoki