jellyfin-ios开发快速入门:从零开始5步本地构建并运行项目

原创2026-11-15 17:29:441,430 阅读

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 界面,并注入了音频、视频播放器等原生能力。

jellyfin-ios 项目 App 图标

二、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 的本地构建与运行:

  1. ✅ 准备 macOS + Xcode + Node 20 环境
  2. ✅ 克隆仓库
  3. ✅ npm install 安装依赖
  4. ✅ npm start 启动开发服务器
  5. ✅ npm run ios 运行到模拟器

接下来可以尝试运行 npm test 查看单元测试,或阅读 screens/HomeScreen.js 等页面源码,开始你的 jellyfin-ios 开发之旅!

登录后查看全文
jellyfin-ios