开发
面向参与本项目的开发者：环境搭建、测试、发布流程与文档结构。
本地开发环境
要求 Node.js ≥ 20（推荐 22）：
npm install
PASSWORD=dev-password npm run dev # http://localhost:8080
PASSWORD本地必填（登录与会话签名依赖它）；- 开发模式不启用
output: 'standalone'（仅 Docker 构建使用，见 Deployment）。
常用命令
| 命令 | 说明 |
|---|---|
npm run dev |
开发服务器（8080 端口） |
npm run build / npm start |
生产构建与启动 |
npm test |
Vitest 单元测试（纯逻辑库 + 部分 Route Handler） |
npm run typecheck |
TypeScript 全量检查 |
npm version patch|minor|major |
升版本并打 tag（发布流程见下） |
测试
单元测试集中在 src/lib 与部分 src/app/api 路由，覆盖核心纯逻辑：
- 解析层：
cms-parser（Apple CMS 列表/详情/详情页爬取、成人内容过滤）、m3u-parser/xmltv（直播与节目单）、source-list/tvbox-parser（订阅格式与 TVBOX 兼容）、env-sources/env-live-sources（预置变量）； - 安全层：
ssrf（内网/保留地址识别、DNS 校验）、auth（会话签名、过期、限流）； - 状态层：
store（订阅同步、健康度自动停用、直播多归属共享）； - 接口层：聚合搜索（跨源去重、置顶、流式）、直播测活等 Route Handler。
约定：业务逻辑尽量下沉到 src/lib 纯函数（不依赖 DOM/网络），Route Handler 只做编排——这是可测试性的前提。新增解析或安全逻辑请同步补测试。
发布新版本
版本号以 package.json 为单一事实来源，镜像由 GitHub Actions 在 v* tag 上自动构建（双架构、GHCR + Docker Hub），详见 Deployment · 镜像分发与版本管理：
npm version patch # 或 minor / major；更新 package.json 并打 git tag
git push && git push --tags
CI 会校验 tag 与
package.json版本一致，不一致直接失败。
文档（本 Wiki）
Wiki 独立成仓（libretv-wiki），与代码仓库同步演进；README 保持精简面向使用者，细节下沉到 Wiki。各页职责边界：
| 页面 | 职责 | 不写什么 |
|---|---|---|
| Home | 导航枢纽、快速开始 | 不重复功能细节 |
| Deployment | 部署、镜像与版本、升级迁移 | 不解释环境变量语义（链到 Configuration） |
| Configuration | 环境变量权威表、用户级运行时设置 | 不重复功能页的行为细节 |
| Data-Sources | 点播源/订阅/分享/健康度的权威说明 | 直播细节归 Live-IPTV |
| Live-IPTV | 直播模块权威说明 | — |
| Recommendations / Player | 对应功能域权威说明 | — |
| Proxy-Security | 鉴权/SSRF/代理设计 | — |
| FAQ | 问题排查，短答案 + 深链 | 不长篇展开 |
| Architecture | 技术栈、目录、数据流、旧版对比 | — |
同一机制多处提及时，非权威页只写一句概述 + 链接（如健康度自动停用以 Data-Sources 为权威），避免多处描述漂移。
目录结构与数据流
见 Architecture。