lottie-react-native 贡献者指南从环境搭建、多平台调试到提交 Pull Request 的完整开发流程【免费下载链接】lottie-react-nativeLottie wrapper for React Native.项目地址: https://gitcode.com/gh_mirrors/lo/lottie-react-native本指南以 CONTRIBUTING.md 为核心脉络面向希望为 lottie-react-native 提交代码的开发者系统讲解 fork 克隆、依赖安装、Android / iOS / Web 三端联调、代码风格校验、本地文档构建以及 Pull Request 提交流程。读完本文你将掌握一套可以直接照做、可复现的仓库开发工作流并了解命令背后的 monorepo 工程结构从而快速定位问题、验证改动并顺利通过 CI 审查。仓库结构速览先认识 monorepo 布局lottie-react-native 采用 Yarn Workspaces 管理的 monorepo 结构根目录 package.json 中声明了三个工作区packages/*核心库源码工作区即lottie-react-native包本体位于 packages/core包含srcTypeScript 源码、android、ios、windows三端原生实现以及 lottie-react-native.podspec 等发布产物example演示应用工作区位于 example用于在 Android / iOS / macOS / visionOS / Web 上验证库的能力其入口是 example/App.tsx根目录工作区monorepo-root承载公共脚本、发布与版本管理配置。根目录 package.json 的workspaces字段./packages/*与./example决定了npm install/yarn会在仓库根目录统一安装所有工作区的依赖。同时核心包 packages/core/package.json 通过react-native-builder-bob将src目录编译输出到libcommonjs / module / typescript 三种目标因此修改 TypeScript 源码后需要重新构建才能让 example 应用看到最新代码——这正是Web 端不支持热更新、每次需手动构建的根本原因。一、环境搭建从 fork 到跑起 Metro BundlerCONTRIBUTING.md 给出的起步流程是 fork 到自己的组织后依次执行克隆、装依赖、启动打包器# 克隆 fork 后的仓库到本地 git clone https://gitcode.com/gh_mirrors/lo/lottie-react-native.git # 进入本地仓库 cd lottie-react-native # 安装依赖 npm install # 启动打包器Metro Bundler用于开发 npm run run:packager需要特别留意文档中的脚本名是历史命名当前仓库的脚本定义已迁移到 Yarn Workspaces 体系。对比根目录 package.json 中的scripts字段可以看到现在等价于启动打包器的脚本是run:bundler: yarn workspace example start它最终调用的是 example/package.json 中的start: npx react-native start。因此如果执行npm run run:packager报 Missing script 错误请改用npm install npm run run:bundlerMetro 打包器启动后会监听 8081 端口之后无论是 Android、iOS 还是 Web 的调试都依赖它提供 JS Bundle。仓库要求 Node 版本为 18见根目录 package.json 的engines.node字段这是配置环境时的重要前提。二、Android 平台开发一行命令构建并启动保持打包器运行、并已连接 Android 真机或模拟器后执行npm run run:android该命令实际映射到 example 工作区的android: npx react-native run-android。它会调用 Gradle 编译原生工程并安装到设备。example 的 Android 工程位于 example/android通过 example/android/settings.gradle 引入依赖。需要验证Fabric新架构时example 提供了专用脚本见 example/package.jsonORG_GRADLE_PROJECT_newArchEnabledtrue npx react-native run-android # 即脚本 fabric:android仅做 CI 构建不启动应用时可分别使用npx react-native build-android # 旧架构Paper ORG_GRADLE_PROJECT_newArchEnabledtrue npx react-native build-android # 新架构FabricAndroid 原生实现分布在 packages/core/android/src/main/java/com/airbnb/android/react/lottie核心逻辑与事件类以及 packages/core/android/src/newarch / packages/core/android/src/oldarch按架构区分的 ViewManager。改动这些 Kotlin 文件后run:android会自动触发 Gradle 增量编译。三、iOS 平台开发先装 Pods 再运行iOS 与 Android 的关键区别在于首次运行前必须下载 iOS 原生依赖CocoaPodsnpm run build:pods该命令对应 example 工作区的ios: pod install --project-directoryios npx react-native run-ios前半段——先执行pod install。example 的 Podfile 使用react-native-test-app的use_test_app!来组装示例工程workspace 名为Example.xcworkspace这也是为何 ios 目录下只有 Podfile 而没有手写 Xcode 工程的原因。Pods 安装完成后保持打包器运行并连接 iOS 真机或模拟器执行npm run run:ios它会完成剩余的npx react-native run-ios。iOS 原生源码位于 packages/core/ios/LottieReactNativeSwift 实现如AnimationViewManagerModule.swift、ContainerView.swift与 packages/core/ios/FabricFabric 组件视图。验证 Fabric 新架构时example 提供三类 CI 脚本见 example/package.jsonRCT_NEW_ARCH_ENABLED1 pod install --project-directoryios npx react-native run-ios --no-packager # 静态框架USE_FRAMEWORKSstatic RCT_NEW_ARCH_ENABLED1 ... # 动态框架USE_FRAMEWORKSdynamic RCT_NEW_ARCH_ENABLED1 ...改动 Swift 文件后iOS 工程的构建阶段会自动调用 SwiftLint见下文第四节若代码不合规会在构建时报错。四、Web 平台开发构建库 启动 webpack 演示Web 端的开发流程在文档中略有差异需要三步# 1. 安装全部依赖 yarn # 2. 构建库每次改动后都需重新构建example 演示应用暂不支持热更新 yarn setupyarn setup在根目录 package.json 中定义为yarn workspace lottie-react-native build即运行react-native-builder-bob把 packages/core/src 编译到lib。Web 端渲染走的是 packages/core/src/LottieView/index.web.tsx它复用lottiefiles/dotlottie-react核心包将其声明为可选 peerDependency。# 3. 启动演示应用访问终端打印的地址 yarn paper:web同理paper:web也是历史命名当前对应脚本是根目录的run:web即yarn workspace example web最终执行 example 的web: webpack serve相关配置见 example/webpack.config.js 与 example/index.web.js。启动后终端会打印本地服务地址默认 http://localhost:8080 附近浏览器打开即可看到演示动画。Web 端不支持热更新的原因在于浏览器加载的是构建产物lib而非src源码所以每次修改 packages/core/src 下的 TS 源码后都要重新跑yarn setup。五、代码风格与 LintESLint SwiftLint 双通道把关本仓库遵循 Airbnb JavaScript 风格指南并通过 ESLint 强制校验npm run lint该命令对应 example 工作区的lint: eslint .eslint 配置基于react-native/eslint-config与react-native-community/eslint-config分别见 example/package.json 与 packages/core/package.json 的 devDependencies。文档建议为编辑器安装 ESLint 插件以便在编码时实时发现违规npm run lint则用于提交前全量自检。针对 iOS 原生包仓库使用SwiftLint需要先在机器上安装brew install swiftlint随后可在 JS 侧调用yarn lint:swift即yarn workspace lottie-react-native lint:swift最终执行swiftlint ios见 packages/core/package.json。SwiftLint 同时也是 iOS 工程 build phases 的一部分因此在 Xcode 构建时会自动运行无需手动触发。若需要自动修复 Swift 风格问题可运行yarn workspace lottie-react-native lint-fix:swift即swiftlint --fix ios。提示提交前请同时通过npm run lint、yarn lint:swift与 TypeScript 类型检查yarn tsc即 example 的tsc --noEmit这是保证改动可被快速合并的基本礼仪。六、本地构建文档GitBook 即时预览仓库文档基于 GitBook 构建配置见根目录 book.json标题 Lottie React Native入口文档为 docs/README.md术语表为 docs/GLOSSARY.md。本地预览只需一条命令npm run docs:watch之后浏览器打开终端提示的端口通常为 http://localhost:4000即可查看文档站点。docs:watch启动监听模式源码文件一旦变动浏览器会自动刷新非常适合边改文档边校对排版。如果该命令在当前仓库版本中报错可检查是否缺失 GitBook 相关全局依赖gitbookCLI因为 book.json 声明的是gitbook: 2.x.x在仓库根目录安装并初始化 GitBook 后重试即可。七、Pull Request 提交流程规范提交 PR 前请逐条对照以下清单源自 CONTRIBUTING.md 的 PR Guidelines功能型 PR 必须同步更新文档新增能力要在 docs 下补充对应说明且与代码改动放在同一个 PR 中功能型 PR 必须更新示例应用在 example/App.tsx 中加入演示新功能的代码同样保持同一个 PR 提交PR 描述要写清动机与用例说明这个功能解决什么问题、典型使用场景是什么便于维护者评估Bug 修复型 PR 要说明复现方式描述 bug 的具体表现、如何复现帮助 reviewer 验证修复有效性提交前先 rebase 并解决冲突确保分支基于最新主干避免合并时产生冲突。补充建议提交信息请遵循仓库使用的 Conventional Commits 约定根目录 package.json 的 release-it 配置使用angularpreset 生成 CHANGELOG.md格式如feat: .../fix: .../chore: ...。核心包的发布由release-it结合 workspace 插件自动完成见 package.json 的release-it配置块规范化的提交信息是自动生成变更日志的基础。八、总结贡献一份改动的完整路径将以上流程串联起来一次完整的贡献大致是fork 仓库并git clone在根目录npm install启动 Metronpm run run:bundler历史文档写法为npm run run:packager按目标平台运行npm run run:android/ 先npm run build:pods再npm run run:ios/ Web 端执行yarnyarn setupyarn paper:web编码过程中利用 ESLint 插件与 SwiftLintyarn lint:swift即时校验提交前跑npm run lint与yarn tsc按 PR 清单补充文档、示例、动机说明rebase 消除冲突后提交。这套流程既适用于修复 lottie-react-native 三端渲染的 bug也适用于为LottieView组件packages/core/src/LottieView/index.tsx添加新属性与平台能力——理解 monorepo 的构建链路src → bob build → lib → example 消费是高效调试的关键也是本文希望为你建立的核心心智模型。【免费下载链接】lottie-react-nativeLottie wrapper for React Native.项目地址: https://gitcode.com/gh_mirrors/lo/lottie-react-native创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考