hectorqin
8584d7b4e3
Unify media secondary page chrome, loading states, playback controls, favorites filtering, and source/library screens with the legacy reader experience.
5.2 KiB
开发指南
环境
- 推荐 Node.js 24，与当前容器和 CI 保持一致；服务端使用内置
node:sqlite。 - npm、Git；服务端和 Web 各有独立
package.json与锁文件，仓库根目录没有统一 npm 脚本。 - UI 评审需要 Chromium。
- 构建 Android 另需 JDK 17+、Android SDK 35、Build Tools 35.0.1；Web 资源构建脚本需要 POSIX shell（Windows 可使用 Git Bash 或 WSL）。
以下命令从仓库根目录执行。
安装依赖
npm ci --prefix server
npm ci --prefix web
界面评审使用 Chromium，在 Web 目录安装：
cd web
npx playwright install chromium
Linux CI 可使用 npx playwright install --with-deps chromium 安装所需系统库。也可设置 CHROME_PATH 指向现有 Chrome/Chromium。
启动开发服务
在仓库根目录开两个终端。使用测试书库，不要把数据目录放进书库里。
Linux/macOS：
mkdir -p /tmp/reader-dev-books /tmp/reader-dev-data
BOOKS_DIR=/tmp/reader-dev-books DATA_DIR=/tmp/reader-dev-data npm run dev --prefix server
PowerShell：
$env:BOOKS_DIR = Join-Path $env:TEMP 'reader-dev-books'
$env:DATA_DIR = Join-Path $env:TEMP 'reader-dev-data'
New-Item -ItemType Directory -Force -Path $env:BOOKS_DIR, $env:DATA_DIR | Out-Null
npm run dev --prefix server
第二个终端：
npm run dev --prefix web
访问 http://localhost:5174。Vite 默认把 /api 代理到 http://127.0.0.1:5888；通过 READER_SERVER 环境变量可调整代理目标。
检查与测试
按修改范围执行，以下是各模块入口：
npm run typecheck --prefix server
npm test --prefix server
npm run build --prefix server
npm run typecheck --prefix web
npm test --prefix web
npm run build --prefix web
Web 测试同时包含 Vitest 和 Node 测试。UI 评审使用真实 Chromium；浏览器缺失时按上面的步骤准备环境。不要把历史测试数量当作当前验证结果。
UI 改动可运行 npm run ui:review --prefix web，书源流程可运行 npm run ui:sources --prefix web。评审脚本位于 web/tools/ui-review/，会把截图和报告写入被 Git 忽略的 artifacts/ui-review/；不要把一次运行的截图提交到 docs/。
构建与运行
单容器镜像
docker build -f server/Dockerfile -t reader:local .
构建上下文必须是仓库根目录，镜像会同时构建 Web 和服务端。可执行 docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build 使用源码部署；后续管理也保留两个 -f 参数。
不使用容器
先执行两端的 npm run build，再从仓库根目录启动：
BOOKS_DIR=/tmp/reader-dev-books DATA_DIR=/tmp/reader-dev-data WEB_DIR="$PWD/web/dist" npm start --prefix server
PowerShell 中先设置 $env:BOOKS_DIR、$env:DATA_DIR，并将 $env:WEB_DIR = (Resolve-Path 'web/dist').Path，再运行 npm start --prefix server。WEB_DIR 需要指向产物目录，服务端不会自动猜测另一个项目中的 web/dist。
Android
从仓库根目录构建 Web 资源，再构建 APK：
sh android/scripts/build-web-assets.sh
cd android
./gradlew :app:assembleDebug
Windows 原生终端使用 gradlew.bat。产物为 android/app/build/outputs/apk/debug/app-debug.apk。可通过 -PdefaultServerUrl=http://nas.local:5888 预设地址；未预设时由用户填写服务地址并登录。编译 APK 不等于完成真机阅读验证。
代码导览
| 目录 | 责任 |
|---|---|
server/src/config、db |
运行时配置、SQLite schema 和访问层 |
server/src/indexer |
文件格式、扫描、身份与元数据 |
server/src/services、http |
业务服务、API、鉴权和资源交付 |
server/src/media |
影音目录、扫描、资料与播放服务 |
web/src/features/media |
影音页面、组件、服务、主题与播放器 |
server/src/sources |
本地书库与 OPDS 接入 |
web/src/formats |
EPUB、TXT、漫画等格式处理 |
web/src/ui、styles |
共享交互、命令式阅读舞台和阅读样式 |
web/src/core、store |
平台能力、同步、离线存储 |
android/app/src/main/java/cool/cnb/reader |
Android Activity、WebView、原生图片和语音桥接 |
应用界面使用 React 19 和 React Router，服务端数据使用 React Query，共享客户端状态使用 Zustand；阅读内容布局与测量由命令式阅读舞台管理。基础交互组件使用 Mantine，图标使用 Lucide React，书籍样式通过 Shadow DOM 隔离。Web 产物由服务端和 Android 共同使用。详细取舍见架构文档和界面规范。
贡献流程
- 描述问题、复现步骤和期望行为；日志、书源及示例请移除凭据。
- 将修改限制在相关模块，参考已有错误语义和测试方式。
- 为行为变更补充适当的回归验证；纯文档修改检查链接、命令和示例即可。
- 提交变更时说明改动、验证方式和已知限制。