jellyfin-ios开发快速入门:从零开始5步本地构建并运行项目
jellyfin-ios开发快速入门:从零开始5步本地构建并运行项目
jellyfin-ios 是 Jellyfin 官方 iOS 客户端,基于 Expo(React Native)构建,用 TypeScript 编写。本文带你从零开始,5 个步骤完成 jellyfin-ios 的本地构建与运行,帮助你快速上手这个开源项目的开发。
一、认识 jellyfin-ios 项目
在动手之前,先了解一下这个项目用了什么技术:
| 技术 | 用途 |
|---|---|
| Expo | 移动开发框架 |
| TypeScript | 开发语言 |
| React Navigation | 页面导航 |
| React Native Elements | UI 组件库 |
| Zustand | 状态管理 |
| Jest | 单元测试 |
💡 简单来说:jellyfin-ios 是一个"Web 视图 + 原生增强"的混合应用,通过 WebView 加载 Jellyfin 的 Web 界面,并注入了音频、视频播放器等原生能力。
二、5步本地构建与运行
第1步:准备开发环境
jellyfin-ios 只面向 iOS 平台,因此必须准备以下环境:
- macOS 系统(iOS 应用只能在 Mac 上构建)
- Xcode(含命令行工具,建议 Xcode 15 以上)
- Node.js ≥ 20.0.0(package.json 中
engines.node明确要求) - npm(⚠️ 项目已停止使用 yarn,必须用 npm)
第2步:克隆代码仓库
打开终端,执行以下命令克隆项目并进入目录:
git clone https://gitcode.com/gh_mirrors/je/jellyfin-ios
cd jellyfin-ios
第3步:安装项目依赖
在项目根目录执行:
npm install
这一步会自动安装 package.json 中列出的全部依赖(包括 expo、react-native、zustand 等)。另外,安装后会自动应用 patches/ 目录下的补丁文件(如 boost1760.patch、xcode15.patch),用于修复 React Native 的原生构建问题,无需手动操作。
第4步:启动开发服务器
npm start
该命令实际执行的是 expo start --dev-client,会启动 Expo 开发服务器。此时请根据终端或浏览器窗口中的提示,选择在你的 iPhone 设备或模拟器上打开应用。
应用入口是 index.js(通过 registerRootComponent 注册主组件),核心逻辑在 App.js 中,包括主题切换、国际化加载、下载处理器初始化等。
第5步:构建并运行到模拟器
如果终端方式不便,可以直接用以下命令构建原生工程并运行到 iOS 模拟器:
npm run ios
该命令等价于 expo run:ios,会自动执行 ios/ 目录下的原生工程(包含 Podfile 依赖安装)并启动模拟器。首次构建时间较长,耐心等待即可。
三、常用 npm 脚本速查
| 命令 | 作用 |
|---|---|
npm start |
启动 Expo 开发服务器(dev-client 模式) |
npm run ios |
构建并运行 iOS 应用 |
npm run build |
执行 prebuild 生成 iOS 原生工程 |
npm test |
运行 Jest 单元测试(watch 模式) |
npm run lint |
执行 ESLint 代码检查 |
四、项目目录结构速览
跑通项目后,建议花几分钟了解目录布局,方便后续二次开发:
├── assets # 静态资源(含注入 WebView 的 JS 脚本)
├── components # React UI 组件
├── features # 功能模块(如 downloads 下载功能)
├── hooks # 自定义 React Hooks
├── ios # Expo prebuild 生成的 iOS 原生工程
├── langs # 多语言翻译文件
├── navigation # React Navigation 导航器
├── screens # 页面组件(首页、设置、添加服务器等)
├── stores # Zustand 数据仓库
├── themes # 主题配置(深色/浅色)
└── utils # 工具函数
更多开发规范(新文件必须用 TypeScript、API 调用必须使用 Jellyfin SDK 等)请阅读 CONTRIBUTING.md,构建流程官方说明见 README.md。
五、常见问题
Q1:npm install 后启动报 Node 版本错误?
升级 Node.js 到 20 以上:node -v 可检查当前版本。
Q2:提示 yarn 相关报错? 项目已全面改用 npm(package.json 中有明确提示),请卸载或用 npm 替代 yarn。
Q3:构建原生工程时出现 Xcode 报错?
检查 patches/ 中的补丁是否随 npm install 正确应用,并确保 Xcode 版本符合要求。
六、总结
至此,你已经完成 jellyfin-ios 的本地构建与运行:
- ✅ 准备 macOS + Xcode + Node 20 环境
- ✅ 克隆仓库
- ✅
npm install安装依赖 - ✅
npm start启动开发服务器 - ✅
npm run ios运行到模拟器
接下来可以尝试运行 npm test 查看单元测试,或阅读 screens/HomeScreen.js 等页面源码,开始你的 jellyfin-ios 开发之旅!