Files

T

eddy 738275b493 feat: 添加 Service Worker 缓存与更新流程

- 为同源资源添加网络优先策略，并在离线时回退到缓存
- 缓存带版本号的 CDN 资源，并在发布更新时保留独立缓存条目
- 改进版本更新检查，避免清除 localStorage 或无关缓存
- 将 Service Worker 纳入部署流程并更新相关文档

2026-07-20 02:22:15 +08:00

5.4 KiB

Raw Blame History

AI 英语助教

一个纯前端的英语单词学习应用。无需后端，学习数据保存在浏览器 localStorage；可导入词库、从邮件提词、进行测试和错题复习，并支持可选的 OpenAI 兼容 AI 服务。

仓库包含两个可独立运行的版本：

src/：当前单文件式实现（index.html、styles.css、script.js）。
refactor/：ES Modules 重构版；按页面、服务、UI 与样式拆分，保持原有功能和数据兼容。

启动

应用需要通过 HTTP 服务运行，不能直接打开 HTML 文件。

# 在仓库根目录运行
python -m http.server 8000

开发原版 src/ 时，Windows 10 可用仓库根目录的脚本一键控制服务：

python serve.py start   # 后台启动，访问 http://localhost:8000/
python serve.py status  # 查看运行状态
python serve.py stop    # 停止服务

脚本不生成 PID 文件，而是通过 8000 端口识别 src/ 的本地 HTTP 服务；当端口被其他程序占用时，可在提示后选择强制关闭该进程并启动。

打开：

原版：http://localhost:8000/src/（使用上述根目录命令）或 http://localhost:8000/（使用 serve.py）
重构版：http://localhost:8000/refactor/

也可启动重构版预设脚本：

cd refactor
npm run serve

该脚本会将仓库根目录作为 HTTP 根目录，因此可正确读取根目录的 data/ 词库。两版若要共享已有学习数据，必须使用相同的协议、主机和端口；localStorage 按 origin 隔离。

功能概览

单词库：JSON 导入与导出、搜索、分类与收藏筛选、详情和发音。
学习与复习：基于 [1, 2, 4, 7, 15, 30] 天间隔的复习计划、错题卡片复习与学习统计。
测试：英译中、中译英、本地或 AI 出题、错题与收藏范围测试。
邮件学习：从英文邮件提取词汇、批量翻译入库、全文阅读、高亮、朗读与 AI 分析。
设置：主题、AI 配置、词库自动加载、完整数据备份与恢复。

技术与外部服务

原生 HTML、CSS、JavaScript；重构版使用浏览器原生 ES Modules，无构建步骤。
Font Awesome、Chart.js。
Free Dictionary API、Azure TTS、有道 TTS 与浏览器 Web Speech（网络语音不可用时回退到浏览器朗读）。
OpenAI 兼容 Chat Completions API（可选，用于出题、翻译和邮件分析）。

CDN 或第三方 API 被网络、离线环境或 CSP 阻止时，相应的图标、图表、AI 或网络语音功能会受限。

数据与兼容性

核心数据包括单词、练习记录、复习计划、收藏、邮件、主题与 AI 设置。重构版沿用原版的数据结构，并支持将默认词库的旧键（如 words、records、schedule、favorites）迁移为按词库分组的存储键。

重构版的主要目录：

refactor/js/core/：状态、存储、路由与事件委托。
refactor/js/services/：TTS、AI、复习算法、统计、出题、提词与词库服务。
refactor/js/pages/：各页面和学习流程。
refactor/js/ui/：主题、侧边栏、Toast、Modal 与 DOM 工具。
refactor/styles/：按原样式级联顺序拆分的样式文件。

重构版不使用内联事件处理器；交互通过命名空间化的 data-action 和统一事件委托处理。

验收

重构版的手工验收清单位于 refactor/docs/smoke-test.md。验证时请在开发者工具中检查 Console，并确认两版使用同一 origin 后再检查历史数据。

发布与缓存

Linux 服务器可使用 deploy.sh 一键下载并部署 main 分支的最新版本：

保留 deploy 参数，以便下载脚本后直接执行部署，而不是进入交互菜单。

bash <(curl -fsSL https://gitea.tohub.top/Share/AI_English/raw/branch/main/deploy.sh) deploy

脚本会将 src/index.html、src/sw.js、src/js/ 和 src/styles/ 部署到 /root/data/docker_data/Nginx/html/english/ai/，清理目标目录中的其他内容，但保留已有的 data/ 目录。运行前请确认目标路径符合服务器配置；脚本需要 root 权限以及 curl、tar、find 命令。

缓存策略分两层：src/index.html 通过 CSS 和入口 JavaScript URL 的 v 查询参数（ASSET_VERSION）控制静态资源缓存，每次发布请同步递增该版本号；src/sw.js（Service Worker）对同源请求采用「网络优先、离线回退缓存」——未带版本号的请求以 cache: 'no-cache' 强制向服务器做条件校验，绕过浏览器启发式缓存（iOS Safari 卡旧版本的根因），带 ?v= 的资源则走默认 HTTP 缓存；对 CDN 上带版本号的静态库（Font Awesome、Chart.js）采用「缓存优先」，首次取回后离线也能显示图标与图表，其余跨域请求（AI / TTS 接口）不拦截。服务器应优先为 index.html 与 sw.js 设置 Cache-Control: no-cache；带版本号的静态资源可长期缓存。

设置页的“获取最新版本”会检查并更新 Service Worker，再通过带时间戳的 URL 重新加载；重新取得的资源会更新对应 URL 的缓存，带版本号的资源会保留独立条目以避免并发页面互相覆盖，且不会清除 localStorage，以免丢失学习数据和 AI 配置。

5.4 KiB Raw Blame History Unescape Escape