企业官网建设流程全解析

• 移动开发
• UI组件

Litho 是 Meta（Facebook）开源的 Android 声明式 UI 框架，本仓库是其在 GitHub 上的镜像与开发主阵地。本文以仓库根目录的 CONTRIBUTING.md 为主线，完整梳理参与 Litho 开发所需的环境准备、构建流程、测试命令、Pull Request 提交规范、Issue 报告要求与代码风格约束，并结合当前仓库中的 settings.gradle、gradle.properties、BUCK 等真实配置与 litho-it 测试布局，为你提供一份可直接照做的贡献实操指南。读完本文，你将掌握从零拉取代码、在本地跑通构建与测试，到合规提交第一个补丁的完整链路。

一、从源码构建：环境准备与项目导入

参与任何代码改动之前，第一步是让项目在本地成功构建。Litho 是典型的 Android 多模块 Gradle 工程，构建依赖既有 Android SDK 组件，也有原生的 Yoga 布局引擎（C/C++）参与编译，因此环境要求比普通纯 Java 项目更严格。

1.1 必备的 Android SDK 组件

CONTRIBUTING.md 明确列出了构建 Litho 需要满足的三项 SDK 依赖：

在 Android Studio 中，可通过SDK Manager → SDK Tools勾选安装 NDK、CMake 和 LLDB，再通过SDK Platforms安装 Android 8.0（API 26）。需要注意，仓库内还提供了 scripts/android-setup.sh 脚本，用于自动化完成部分环境准备工作，本地首次搭建环境时可以参照执行。

1.2 仓库实际的构建配置现状

为了让构建环境与当前仓库版本对齐，这里补充几个来自仓库本身的版本信息，帮助你判断自己机器上的工具链是否匹配：

• Gradle Wrapper：仓库根目录的 gradle/wrapper/gradle-wrapper.properties 将 distributionUrl 固定为gradle-8.1-all.zip，因此使用./gradlew会自动下载 Gradle 8.1，无需手动安装 Gradle；
• 项目版本与坐标：gradle.properties 中定义了VERSION_NAME=0.51.0-SNAPSHOT、GROUP=com.facebook.litho，即当前仓库处于 0.51.0 的快照开发阶段，同时声明了 Kotlin 版本1.9.22以及 AndroidX 支持开关（android.useAndroidX=true）；
• 模块清单：settings.gradle 列出了全部 Gradle 子模块，包括litho-core、litho-widget、litho-sections-*、litho-rendercore系列、litho-processor、litho-annotations以及sample、sample-barebones、sample-codelab等示例工程。其中yoga、yogajni被重定向到 lib/yoga 与 lib/yogajni，test-processor与test-specs被重定向到 litho-it 下，导入工程后这些映射会自动生效。

1.3 导入项目与首次 Sync

环境就绪后，按照 CONTRIBUTING.md 的指引：

1. 克隆仓库到本地；
2. 确认上述 SDK 组件已安装；
3. 在 Android Studio 中通过File → Open选择仓库根目录（即包含settings.gradle的目录）导入工程；
4. 等待 Gradle Sync 成功。若 Sync 报错，优先检查 NDK/CMake 是否安装、API 26 平台与 Build Tools 27.0.3 是否就位。

需要说明的是，原文档中的 SDK 版本要求是项目在对应时期的标准配置；如果本机已安装更高版本的 SDK 平台与构建工具，Sync 过程中可能仍需要按提示补充安装 API 26 或指定版本的工具链，以保持与仓库配置一致。

1.4 构建产物与 BuildConfig 生成

除了 Gradle 路径，仓库同时保留了 Facebook 内部使用的Buck构建支持（根目录 BUCK）。其中值得关注的是build_config目标的实现：它读取 config/build_config_values 中的占位内容（如boolean IS_INTERNAL_BUILD = {{IS_DEBUG}}），通过genrule将{{IS_DEBUG}}替换为read_config("litho", "is_debug", "true")的取值，最终生成com.facebook.litho包下的 BuildConfig 类。这解释了为什么在代码中可以通过构建配置区分内部构建与开源构建——理解这一点，有助于你判断哪些改动在开源构建中会被条件编译。

二、开发流程：内部分支与开源镜像的同步机制

CONTRIBUTING.md 明确指出，Litho 的日常开发发生在Facebook 内部的私有分支上，开源仓库会定期从内部仓库同步变更；外部贡献者的 Pull Request 则会被cherry-pick 进内部仓库，再随下一次同步推送回 GitHub。

这一流程对外部贡献者有两层含义：

• 主干永远以 master 为基准：内部代码与开源代码最终会汇合到同一个主干，因此你的分支应当从 master 拉出，避免基于旧版本或他人未合并的分支开发；
• 合并节奏由维护者控制：PR 通过评审后，维护者会将其带入内部开发流程，再以同步的形式回到开源仓库，因此从提交到出现在 master 上可能经历两个阶段，属正常现象。

三、测试：改代码前先跑通测试套件

CONTRIBUTING.md 的要求非常明确：改动代码时，必须保证现有测试全部通过，并为新功能补充恰当的测试。

3.1 两种测试入口

其中./gradlew test会遍历 settings.gradle 中注册的全部模块并执行各自的测试任务；如果只想验证某个模块，可按 Gradle 惯例指定任务路径（例如运行示例工程的构建可用 README 中给出的./gradlew :sample:installDebug）。

3.2 测试代码在哪里

框架核心测试集中在 litho-it 模块，其单元测试源码位于 litho-it/src/test/com/facebook/litho，涵盖动画（AnimationsTest.kt）、通用属性（CommonPropsTest.kt）、组件树（ComponentTreeTest.kt）、动态属性（DynamicPropsTest.kt）、Hook 状态（HooksStateHandlerTest.kt）等数百个测试文件。新增或修改功能时，可以参照这些既有测试的写法：它们大量使用 Litho 自带的测试工具类（如 litho-testing 模块提供的匹配器与断言），保证组件在脱离真实设备的情况下也能被验证布局、挂载与事件行为。

此外，litho-it下还包含processor与specs两个子模块，用于验证注解处理器生成代码的正确性——如果你的改动涉及 litho-processor 或 litho-sections-processor 这类代码生成器，这些测试同样需要同步更新。

四、Pull Request：从 Fork 到合并的六步规范

CONTRIBUTING.md 给出了提交 Pull Request 的完整流程，逐条展开如下：

1. Fork 仓库，并从 master 拉出分支：保证你的分支与最新 master 同步，避免合并冲突；
2. 为新增代码补充测试：测试是评审的门槛，缺少测试的功能通常不会被合并；
3. 变更 API 时同步更新文档：文档统一维护在仓库的 docs 目录下（含.md与.mdx格式），任何公共 API 的签名、语义变化都必须反映到对应文档中，否则会导致文档与代码脱节；
4. 确保测试套件全部通过：即执行上一节的./gradlew test（或buck test ...），以本地验证结果为准；
5. 签署贡献者许可协议（CLA）：如尚未签署，需要先完成一次性的 CLA 提交，才能继续后续流程；
6. 等待维护者评审并合并：评审意见会通过 PR 评论给出，修改后重新推送即可。

这一规范与仓库 README.md 中的 Contributing 指引相互印证——README 同样指向本文所述的贡献流程，并要求贡献者遵守行为准则。

五、贡献者许可协议（CLA）

CONTRIBUTING.md 强调，接受 Pull Request 的前提是提交 CLA，并且只需签署一次，即可适用于 Meta 旗下所有开源项目。

实际操作要点：

• CLA 在代码评审开始前完成即可，但建议在提交第一个 PR 前就处理，避免阻塞合并；
• 签署流程在 Facebook 官方的 CLA 页面完成，提交后会与你的 GitHub 账号关联；
• 如果组织/公司贡献代码，通常需要以企业身份签署，请提前与所在组织的开源合规负责人确认。

六、Issue：如何报告一个高质量的问题

Litho 使用 GitHub Issues 跟踪公开 bug。CONTRIBUTING.md 强调：报告问题提供的信息越多，越容易得到快速响应，并给出了五类关键素材：

• 标题与正文：标题应概括问题现象，正文描述复现步骤、预期行为与实际行为；
• 问题截图或录屏：对 UI 框架类问题尤其重要，画面证据能直接定位渲染异常；
• Logcat 输出：如果应用崩溃，附上崩溃堆栈与相关日志；
• 问题代码片段：给出触发问题的组件代码，便于维护者本地复现；
• 代码块格式：代码必须放进 fenced code block 并标注语言，保证可读性。

CONTRIBUTING.md 给出的标准写法如下：

```java (or xml) your code here ```

即以三个反引号开启代码块，紧跟语言标识java或xml，正文结束后以三个反引号闭合。对于 Kotlin 代码，按同样规则标注为kotlin即可。

安全漏洞：不要公开提交

如果发现的是安全漏洞，CONTRIBUTING.md 明确要求不要提交公开 Issue，而是走 Facebook 的漏洞赏金（bounty）计划所规定的私密披露流程。安全类问题在未修复前公开会带来真实风险，因此必须通过官方披露渠道提交，待处理完成后再考虑公开细节。

七、编码风格：与现有代码保持一致

CONTRIBUTING.md 对代码风格提出了明确且可执行的约束：

需要补充说明的是，当前仓库的代码已经大量迁往 Kotlin（例如 litho-core、litho-widget 中绝大多数源码为.kt文件），而 litho-processor 等模块仍以 Java 为主。因此实践中应遵循两条细则：

• Java 文件按 Google Java Style 编写并跑google-java-format；
• Kotlin 文件遵循项目既有的 Kotlin 惯例（命名、空行、lambda 风格等），同样以相邻代码为准。

简单判断标准：如果你的补丁与周围代码风格不一致，评审阶段几乎必然被要求修改，因此在写第一行代码前先读一读同目录下的文件。

八、License：贡献即授权

CONTRIBUTING.md 最后声明：向 Litho 提交贡献，即表示你同意贡献内容遵循项目的Apache-2.0许可。仓库根目录的 LICENSE 文件即为该许可的完整文本，gradle.properties 中的POM_LICENCE_NAME=Apache-2也印证了发布物采用同样的许可。这意味着：

• 你的代码贡献会被合并进 Apache-2.0 许可的开源项目并随其分发；
• 若你的代码包含第三方依赖或复制片段，需确保其许可与 Apache-2.0 兼容并正确标注来源；
• 提交 PR 前请确认你的雇主/组织允许将相关代码以 Apache-2.0 授权贡献出去。

九、贡献流程全景速查

将以上内容汇总为一份贡献者速查清单：

1. 安装 NDK、CMake、LLDB、API 26 平台与 Build Tools 27.0.3；
2. 克隆仓库，用 Android Studio 打开仓库根目录并成功 Sync；
3. 从 master 拉出功能分支，编写代码（2 空格缩进，风格与相邻代码一致）；
4. 为新功能在 litho-it 等测试模块补充测试；
5. 变更公共 API 时同步更新 docs 下的文档；
6. 运行./gradlew test（或buck test ...）确保全部测试通过；
7. 签署 CLA（一次性）；
8. 提交 PR 等待评审；发现安全漏洞时改走私密披露渠道而非公开 Issue。

这套流程覆盖了从环境搭建到代码合入的完整闭环。对于初次接触 Litho 的开发者，建议先完成第 1、2 步跑通构建，再以 sample 示例工程为参照熟悉框架写法，最后带着测试与文档提交你的第一个补丁。

• 移动开发
• UI组件