Chaptarr 从源码构建指南:.NET 10 后端 + React 前端完整开发环境搭建
Chaptarr 从源码构建指南:.NET 10 后端 + React 前端完整开发环境搭建
Chaptarr 是一款面向有声书(audiobook)和电子书(eBook)的收藏管理工具。本指南带你完成 Chaptarr 从源码构建的完整流程:先准备 .NET 10 SDK 与 Node.js 开发环境,再用 yarn build 编译 React 前端,最后用 dotnet publish 构建后端并运行验证,一套命令即可完成本地开发环境搭建。
1. 开发环境清单:先装好这 4 样工具
Chaptarr 采用 C#/.NET 后端 + React 前端 的经典架构,构建前请确认以下依赖已就绪:
| 工具 | 版本要求 | 用途 |
|---|---|---|
| .NET SDK | 10.0(net10.0 目标框架) |
构建并运行后端 |
| Node.js + Yarn | 推荐 Node 20.11.1 / Yarn 1.22.19(以 package.json 的 volta 段为准) |
构建 React 前端 |
| Git | 任意稳定版 | 克隆代码仓库 |
| FFmpeg + FFprobe | 可选 | 原生运行时的音频转换功能;Docker 官方镜像已内置 |
💡 小贴士:前端依赖版本由 package.json 统一管理,Yarn 请使用 1.x(Classic)版本,与 CI 保持一致。
如果打算本地原生运行并用到 MP3 → M4B 转换功能,需要把 ffmpeg 与 ffprobe 放到启动路径的 PATH 中;二进制文件的查找顺序见 Tools/README.md。
2. 一键克隆仓库
git clone https://gitcode.com/gh_mirrors/ch/chaptarr
cd chaptarr
仓库结构速览(开发时最常打交道的目录):
| 目录 | 说明 |
|---|---|
frontend/src/ |
React 前端源码(Redux 状态、组件、工具函数) |
src/Chaptarr.Api.V1/ |
后端 REST API 控制器与资源定义 |
src/NzbDrone.Core/ |
核心业务逻辑(书籍、下载、索引器等) |
src/NzbDrone.Console/ |
可执行入口项目 |
Tools/ |
FFmpeg/FFprobe 二进制查找目录 |
3. 构建 React 前端:yarn install + yarn build
在仓库根目录执行:
yarn install
yarn build
yarn build实际调用 webpack 以生产模式打包(脚本定义见 package.json),产物输出到根目录的_output/UI/;- 前端代码以 JSX 为主,frontend/tsconfig.json 配置了
allowJs,TypeScript 与 JavaScript 混用; - 只改前端时,可以开一个热更新进程边改边看:
yarn watch。
4. 构建 .NET 10 后端:dotnet publish 单条命令搞定
后端入口项目是 Chaptarr.Console.csproj,目标框架为 net10.0。Linux / macOS 执行:
dotnet publish src/NzbDrone.Console/Chaptarr.Console.csproj -c Release -f net10.0 -o _output/publish
Windows 命令行(CMD)执行同样命令即可,仅注意最终可执行文件名不同:Windows 上为 Chaptarr.Console.dll,Linux/macOS 上为 Chaptarr.dll(命名逻辑见 Chaptarr.Console.csproj)。
构建细节说明:
- 所有项目共享 src/Directory.Build.props 中的统一属性,其中开启了
TreatWarningsAsErrors,即警告也会让构建失败,属于正常行为; - 中间产物集中在仓库根的
_temp/,最终输出统一放到_output/(见 src/Directory.Build.props); - 官方 Docker 镜像的构建流程(
yarn build+dotnet publish的组合)可参考 Dockerfile.cross,与本文步骤完全一致。
5. 合并前后端并启动验证
前端产物挂载到后端目录
后端启动时会直接托管前端静态资源,因此需要把 UI 产物复制进发布目录:
# Linux / macOS
cp -r _output/UI _output/publish/UI
# Windows CMD
xcopy _output\UI _output\publish\UI /E /I
运行 Chaptarr
# Linux / macOS
dotnet _output/publish/Chaptarr.dll
# Windows
dotnet _output\publish\Chaptarr.Console.dll
浏览器打开 http://localhost:8789,首次启动会要求设置管理员账号。若前端资源正常,导航到不存在的路由时会看到 Chaptarr 标志性的 404 页面:
看到这张"图书馆找书"插画,说明 React 前端已成功部署在 .NET 后端之上,开发环境搭建完成 🎉
6. 常见问题排查清单
- 找不到
ffmpeg/ffprobe:仅影响音频转换功能,按 Tools/README.md 通过系统包管理器安装并加入PATH即可; - 构建报大量 CS 警告错误:这是
TreatWarningsAsErrors生效,请修正警告而不是绕过它; yarn install报错:确认 Yarn 为 1.22.x 版本,Node 为 20.x(以 package.json 的volta配置为准);- 端口 8789 被占用:修改配置或释放端口后重启。
7. 下一步:跑测试与阅读贡献指南
# 运行核心单元测试
dotnet test src/Chaptarr.Core.Test/Chaptarr.Core.Test.csproj
后续修改代码、提交 PR 的规范(含数据库迁移目录 src/NzbDrone.Core/Datastore/Migration/ 等路径说明)详见 CONTRIBUTING.md。祝你构建顺利,开始你的 Chaptarr 源码之旅!
