Chaptarr 从源码构建指南:.NET 10 后端 + React 前端完整开发环境搭建

原创2026-10-31 18:51:551,866 阅读

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 页面:

Chaptarr 源码构建后 Web 界面 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 源码之旅!

登录后查看全文
chaptarr