Bangumi 追番记录客户端本地构建指南：从源码安装到真机运行

Bangumi 追番记录客户端本地构建指南从源码安装到真机运行【免费下载链接】Bangumi:electron: An unofficial https://bgm.tv ui first app client for Android and iOS, built with React Native. 一个无广告、以爱好为驱动、不以盈利为目的、专门做 ACG 的类似豆瓣的追番记录bgm.tv 第三方客户端。为移动端重新设计内置大量加强的网页端难以实现的功能且提供了相当的自定义选项。 目前已适配 iOS / Android。项目地址: https://gitcode.com/GitHub_Trending/ba/BangumiBangumi 是一个面向 bgm.tv 的第三方追番记录客户端基于 React Native Expo 开发同时覆盖 iOS 与 Android 双端。它在移动端重新设计了界面除番组进度管理、条目详情、时间线、超展开等站点原有功能外还内置了词云、照片墙、本地文件夹条目管理等网页端难以实现的能力。本文带你完成本地环境的准备、依赖安装、目标平台配置与应用启动并整理出打包阶段常见的故障排查方法帮助你在真机上跑起这套追番记录应用。 确认项目结构与功能边界整个仓库的组成比较清晰src/是 React Native 业务代码android/与ios/是两个原生工程目录packages/负责多环境依赖管理web/存放侧载与发布相关脚本。功能清单与扩展说明可以查阅 README.MD版本更新记录在 web/CHANGELOG.MD。在动手构建之前先明确你要调试的目标平台——作者的原话是有条件优先在 iOS 环境开发安卓端已经脱离 Expo 多年对 JDK 版本和子库版本更敏感。️ 按平台核对环境要求不同平台依赖的工具链差异较大先按下表逐项准备可以避免大部分启动失败组件要求适用平台Node.js最新 LTS 版本配合 yarn 使用全部Git任意稳定版全部JDK必须是 JDK 而非 JRE版本需与 Android 工程匹配AndroidAndroid Studio SDK用于配置 SDK 路径与 USB 调试Androidwatchman监听文件变化缺失会报文件句柄类错误macOS 上的 Android 构建Xcode CocoaPodsiOS 部署目标为 16.4iOS一个容易踩的坑国内网络下首次拉取依赖会很慢且本项目依赖版本较旧、锁得比较严格。README 中明确提示不要使用淘宝镜像源建议直接配置官方源npm config set registry https://registry.npmjs.org 克隆源码并安装全部依赖先克隆仓库到本地工作目录git clone https://gitcode.com/GitHub_Trending/ba/Bangumi进入仓库后用 yarn 安装依赖。之所以指定 yarn 而不是 npm是因为项目内存在跨大版本的旧依赖yarn 的解析方式更不容易出错cd Bangumi yarn install安装完成时postinstall钩子会自动执行 patch-package把patches/目录下的补丁应用到对应依赖上这一步不需要手动干预。⚙️ 用环境脚本切换到目标平台本项目用一套独立脚本管理 iOS / Android / Web 三套依赖切换逻辑与补丁归档规则都写在 packages/README.md 中。不要直接在根目录混装两套依赖先切换到目标环境yarn env android该脚本会备份当前环境的package.json与node_modules再把目标环境的配置恢复到根目录并同步babel.config.js、app.json与补丁软链接。如果你只调试 iOS则执行yarn env ios。切换依赖后回到根目录再执行一次yarn install确保依赖与补丁一致。 配置安卓端并启动调试安卓工程的详细约定在 android/README.MD 中核心流程如下手机打开开发者模式并开启 USB 调试连接电脑后允许调试授权Android 端还需要至少一次通过 Android Studio 连接并授权同时授予应用安装与悬浮窗权限。启动调试进程yarn 会自动编译当前版本并推送到手机yarn dev如果编译成功但 Metro 无法持续启动调试服务可以单独拉起调试进程而不重新打包yarn metro需要产出正式 APK 时先创建签名文件放到android/app/my-release-key.keystore然后把android/gradle_yours.properties复制为gradle.properties并填入签名别名与密码必要时再手写local.properties指定 SDK 路径yarn build构建产物可以直接通过yarn open定位到输出目录。Gradle 配置中 JVM 堆内存默认为 2g见android/gradle_yours.properties如果你的机器内存充足且开启 R8 混淆后仍报堆溢出可以调高org.gradle.jvmargs中的-Xmx值。 配置 iOS 端并启动调试iOS 侧的 CocoaPods 配置在 ios/Podfile部署目标锁定在 16.4Hermes 引擎默认启用。安装原生依赖cd ios pod install回到根目录启动。iOS 端目前运行在 Expo 客户端之上用 Expo Go 类客户端扫码即可调试作者不会引入 Expo 不支持的第三方库这也是 iOS 端最省心的原因cd .. yarn dev️ 用问答方式处理常见构建故障问安卓安装失败提示权限不足怎么办答在出错的命令行前加sudo重试即可。问遇到spawnSync adb ENOENT说明什么答系统找不到 adb通常是 Android SDK 的platform-tools没有加入 PATH确认adb在终端可直接执行后重启 Metro。问昨天还能打包今天 gradle 报 read timeout为什么答gradlew 的依赖缓存只有 24 小时过期后重新拉取时可能遭遇网络波动。可以加--offline参数复用已有缓存或在网络稳定后重试。问macOS 上构建报监听文件过多类的错误答先安装 watchman 再构建。Apple 芯片M1/M2上打包时还要特别注意必须装 JDK 而不是 JRE打包前若仍失败可进入android/执行./gradlew clean后重来。问错误信息里出现 node_modules 下某个包的名字答说明该依赖没有下载完整单独补装该包即可。问试了很多还是跑不起来答不要无限折腾。作者的建议是回到 Expo 官方文档按官方工作流先把环境库装好再执行本项目的命令各类不可预期问题也可以直接重启机器试试。️ 调整可调项做个性化配置跑起来之后有几个入口值得按自己的需求调整Gradle 构建行为android/gradle_yours.properties中的reactNativeArchitectures默认只编arm64-v8a、hermesEnabled、org.gradle.jvmargs都可直接修改改完重新yarn build生效。网络与数据展示客户端把封面与静态数据覆盖到自建 CDN 中间层网页端挂掉时客户端仍可用代理相关行为在 src/utils/proxy/ 中维护安卓端还有一个基于 Rust 的 ECH 本地代理模块构建说明见 android/rust/README.md。代码质量检查样式与导入规则由自研 ESLint 插件约束规则实现在 eslint-rules/可以用yarn lint:styles、yarn test在改动前后做一次自检。把环境、依赖、目标平台三件事做对之后Bangumi 的日常调试基本就是改代码、yarn dev、看真机的循环。遇到构建问题先对照 android/README.MD 与 packages/README.md 查约定多数失败都能在前述问答里找到对应处理真正难以复现的偶发问题重启 Metro 与重建 Gradle 缓存通常是最后一道保险。【免费下载链接】Bangumi:electron: An unofficial https://bgm.tv ui first app client for Android and iOS, built with React Native. 一个无广告、以爱好为驱动、不以盈利为目的、专门做 ACG 的类似豆瓣的追番记录bgm.tv 第三方客户端。为移动端重新设计内置大量加强的网页端难以实现的功能且提供了相当的自定义选项。 目前已适配 iOS / Android。项目地址: https://gitcode.com/GitHub_Trending/ba/Bangumi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考