Fudoki 移动端 UX 优化实录：日语文本分析工具从审计到上线的完整复盘

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

Fudoki 是一款开源的日语文本分析工具，集分词、词性标注、词典查询与语音朗读于一身，非常适合日语学习者边读边查、边听边练。2026 年 8 月，项目团队针对移动端做了一轮系统性的移动端 UX 优化：从无头浏览器走查、Lighthouse 基线采集，到逐项修复、验证上线，形成了一条完整可复用的优化链路。这篇文章把整段实录整理成复盘，无论你是想给自己的 Web 应用做移动端适配，还是单纯好奇"一次靠谱的移动端优化该怎么做"，都值得一看。

为什么日语学习工具必须优先做好移动端

Fudoki 的核心使用场景非常"手机化"：在地铁上遇到一段不认识的日语，复制进来，点一下就能看到每个词的分词、读音、词性，再点一下还能听标准发音。这类高频、碎片化的需求，决定了移动端体验几乎就是产品的生命线。然而此前 Fudoki 的界面是为桌面端设计的，直接拿到 390px 宽的手机上，难免出现布局溢出、按钮太小、功能找不到等一连串问题。

审计先行：390×844 无头浏览器走查 + Lighthouse 基线

动工之前，团队先在 Chromium headless 环境（390×844 视口）对 8 个关键页面逐屏截图，形成一份分级问题清单，完整记录在 移动端走查报告 AUDIT.md 中；同时跑了一轮 Lighthouse v12 移动端基线，结果记在 Lighthouse 基线 LIGHTHOUSE.md 里。审计的核心价值在于把"感觉不好用"翻译成可量化的缺陷，并按影响面分级：

P0 级修复：先解决"打不开、看不见"的硬伤

TTS 控制条改为底部常驻迷你条

这是本轮优化中最关键的一处。修复前#headerPlayControl是文档流内的普通元素，页面一滚动朗读控制条就消失；修复后它变成position: fixed固定贴底，并配合env(safe-area-inset-bottom)避开 iPhone 底部横条，正文区域同步预留出 64px 高度避免遮挡。现在朗读时无论翻到哪一段，播放/暂停、进度、语速都触手可及，实现"边听边读"。

登录页横向滚动与视口修复

登录页的浮动装饰元素定位越界导致整页出现横向滚动条，同时height:100vh在 iOS 地址栏收起时会出现跳变。修复方案是清理越界定位、引入dvh视口单位降级、补上viewport-fit=cover，并给登录页补齐 manifest、theme-color、apple-touch-icon 等 PWA 头部信息——这一步顺带把"添加到主屏幕"体验也做了。

P1 级优化：词典词卡、触控目标与编辑器工具栏

词典词卡加约束：不超屏、可滚动、不误触

Fudoki 的词典词卡要展示词性、读音、释义甚至例句，桌面端没问题，手机上长词条会直接超出屏幕底部。优化后在 移动端样式 mobile.css 中对词卡加了max-width: calc(100vw - 24px)、max-height: 55dvh、内部滚动与overscroll-behavior: contain，长释义还能独立折叠滚动，不再撑破屏幕。

触控目标全面提至 44px

排序按钮、文档操作按钮、工具栏图标、搜索框等触控目标全部加到了 40~44px 以上，播放/暂停按钮明确做到min-width/min-height: 44px，输入框字号提到 16px 防止 iOS 聚焦自动放大。这一改动肉眼几乎看不出来，但误触率明显下降。

EasyMDE 工具栏精简 + 大号预览按钮

移动端工具栏去掉了 link、image 等低频按钮，预览切换按钮做成带"预览/Preview/プレビュー"多语言标签的醒目大按钮，并由 移动端交互脚本 mobile-ux.js 动态注入标签文本，编辑与预览的切换不再需要眯着眼睛找图标。

软键盘弹出视口处理

手机上唤起软键盘时，布局视口高度骤降，底部控制条会被顶得错乱。脚本监听visualViewport高度变化，检测到键盘弹出就给body加kb-open类，控制条自动改为 sticky 贴底、编辑器保持最小高度，避免键盘和输入框互相遮挡。

P2 级体验：下拉刷新与左右滑切换文档

移动端怎么能没有手势？本轮为 Fudoki 补齐了两个高频手势：下拉刷新——在抽屉的文档列表顶部下拉 72px 即触发刷新并带旋转动画指示器；左右滑切换文档——在分析结果区域左滑/右滑即可在上一篇/下一篇文档之间切换，且在选中文字或点击词卡时自动忽略，避免误触。抽屉菜单本身也重新梳理了层级，让文档管理更顺手。

顺带完成的 PWA 可安装性

得益于本轮补齐的登录页头部与安装入口，Fudoki 现在可以顺畅地"安装"到手机桌面：Android 端捕获beforeinstallprompt事件弹出安装 FAB 按钮，iOS 端则每 7 天提示一次"通过分享→添加到主屏幕"完成安装。配合已有的manifest.json（standalone + 192/512 双用途图标）和service-worker.js（fudoki-cache-v2 缓存策略），离线打开、全屏运行都已就绪。

Lighthouse 基线解读：数字背后的取舍

修复后 Lighthouse 移动端基线中，Best Practices 拿到满分 100，CLS 布局稳定性为 0（说明新增的固定控制条、词卡约束没有引入任何布局抖动），这是本轮改动质量最直接的证据。Performance 分数只有 27，但报告明确指出主因是本地无头环境下 Firebase SDK 与约 50MB 的 JMdict 离线词典分块加载所致——这是数据密集型应用（离线词典 + 本地分词引擎）的固有基线特征，真机 Wi-Fi 环境下感知要好得多。这也提醒我们：性能分数要结合应用类型解读，不能唯分数论。

复盘总结：一次移动端优化的可复用流程

回顾这次 Fudoki 移动端 UX 优化，最值得借鉴的不是某一处代码，而是这条完整闭环：

1. 无头浏览器批量截图走查，把问题分级为 P0~P3，先修硬伤再谈体验；
2. Lighthouse 建立基线，让后续每次改动都有可对比的量化指标；
3. 修复遵循"先约束后增强"：先保证不越界、不遮挡、不误触，再叠加手势、PWA 等增强体验；
4. 全程关注安全区与视口：dvh、env(safe-area-inset-*)、visualViewport是移动端 Web 的三件套；
5. 纯体验层解耦：所有交互增强集中在 mobile-ux.js 一个文件，不触碰数据与业务逻辑，风险可控、回滚方便。

从审计报告到修复上线的完整复盘，就是上面这些。如果你也在做日语学习工具或任何需要移动端适配的 Web 应用，这套"走查 → 定基线 → 分级修复 → 数据验证"的打法，可以直接复制到自己的项目里。📱

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