知乎++开发者完整教程：源码构建、双变体打包、CI测试与贡献规范一次讲透-创锋一号

知乎++开发者完整教程：源码构建、双变体打包、CI测试与贡献规范一次讲透

【免费下载链接】zhihu-plus-plusZhihu++ | 知乎++: Ad-free, low cost, AI powered zhihu android 3rd-party client. 去广告、占用低、AI大模型的新时代知乎安卓端体验项目地址: https://gitcode.com/gh_mirrors/zh/zhihu-plus-plus

知乎++（Zhihu++）是一款去广告、低内存占用、支持 AI 大模型能力的知乎安卓第三方客户端。本教程面向想参与开发的新手，一次讲清源码构建步骤、full/lite 双变体打包、CI 自动化测试链路与贡献规范，帮助你在一个晚上完成第一个可安装的 APK，并提交一个符合规范的 PR。

一、项目速览：知乎++是什么、代码放在哪里

知乎++的核心卖点：去广告、去推广软文、屏蔽盐选付费内容，独创本地推荐算法（推荐完全在本地计算，不被算法"投喂"），并内置基于 LLM embedding 的 AI 智能内容过滤、Markdown/LaTeX 渲染与内容创作能力。

项目基于Kotlin Multiplatform（KMP），一套核心代码同时支撑 Android、实验性桌面端与 macOS。在 settings.gradle.kts 中可以看到全部模块编排，主要模块一览：

目录	职责
app/	Android 应用壳，定义 full/lite 双变体
shared/	KMP 跨平台核心：UI、数据、账号、Markdown 渲染
shared-local-db/	本地数据库（历史记录、收藏夹等）
desktopApp/	实验性桌面端（Windows / Linux，内置 Java 运行时）
macosApp/	macOS arm64 原生端
sentence_embeddings/	端侧句向量 AI 模型，仅 full 变体
third_party/	内置的 markdown / LaTeX / 代码高亮渲染库
aigc-vote-server/	Rust 编写的 AIGC 标记投票服务
rs-zse-sign/	Rust 实现的 zse96 签名算法
misc/	浏览器广告过滤插件、油猴脚本、表情包等周边工具

当前版本号维护在 gradle.properties：versionName=0.30，versionCode=747，构建产物会自动带上这两个值。

二、环境准备与源码构建：从克隆仓库到第一个 APK

环境要求（3 件套）

JDK 17（CI 使用 Zulu 发行版，本地保持一致最稳妥）
Android SDK：项目compileSdk=37、minSdk=27（Android 9+）、targetSdk=35
Android Studio：直接打开仓库根目录即可识别 Gradle 工程

构建加速已开箱即用：gradle.properties 中默认开启了 4G 堆内存、并行构建、构建缓存与 KSP 增量处理，首次构建稍慢，二次构建会明显变快。

一键克隆仓库

git clone https://gitcode.com/gh_mirrors/zh/zhihu-plus-plus

新手最常用的 5 条 Gradle 命令

命令	用途
`./gradlew ktlintCheck`	代码风格检查（CI 门禁同款）
`./gradlew assembleLiteDebug`	打包 lite 变体 debug APK
`./gradlew assembleFullDebug`	打包 full 变体 debug APK
`./gradlew :shared:jvmTest :app:testLiteDebugUnitTest`	运行单元测试（与 CI 完全一致）
`./gradlew :desktopApp:packageReleaseDistributionForCurrentOS`	打包当前系统的桌面版

lite debug APK 产出在app/build/outputs/apk/lite/debug/app-lite-debug.apk，可直接安装到手机。另外，debug 与 release 构建都会把当前 Git commit 写入GIT_HASH常量（见 app/build.gradle.kts），方便排查问题时确认"我跑的是哪份代码"。

三、双变体打包：full 与 lite 怎么选

知乎++通过 GradleproductFlavors实现双变体打包，这是 app/build.gradle.kts 里的核心配置，两者差异如下：

维度	lite（默认变体）	full
包体积	小于 4 MB	更大（内置 ONNX 推理框架与模型）
AI 智能过滤	不支持	基于 LLM embedding 的向量相似度屏蔽回答
applicationId	`com.github.zly2006.zhplus.lite`	`com.github.zly2006.zhplus`
依赖差异	—	额外依赖 sentence_embeddings/ 与 HanLP

配置上有两个值得注意的细节：

每个变体都会注入IS_LITE布尔编译常量，代码里靠它区分行为，而不是靠判断包名；
release 打包时，只有 lite 变体启用 R8 混淆与资源缩减（isMinifyEnabled按变体名判断），full 变体因包含原生模型文件，关闭混淆以避免裁剪出错。

想产出一个可发布的 release 包，本地构建需要配置签名环境变量（signingKey为 Base64 编码的 jks、keyStorePassword、keyAlias、keyPassword），然后执行：

./gradlew assembleLiteRelease

📦 官方对两个变体的定位见 README.md：full 主要承载端侧 AI 技术尝试，Lite 更小更快，按需选择。

四、CI 测试流水线：PR 提交后自动执行了哪些检查

提交 PR 后，.github/workflows/pr.yml 定义的检查流水线会自动运行，共 5 个任务：

Job	执行内容	作用
ktlint	`./gradlew ktlintCheck`（JDK 17）	代码风格门禁，不通过直接失败
build_pr	`./gradlew assembleLiteDebug`，按需追加测试 APK 构建	验证编译，并产出 debug APK 供下载
unit-tests	`:shared:jvmTest`+`:app:testLiteDebugUnitTest`（JDK 23）	跨平台核心逻辑单元测试
desktop-jar	`:desktopApp:packageReleaseDistributionForCurrentOS`	验证桌面端 release 打包链路
mock-instrumented-shards	API 36 Pixel 7 模拟器，5 分片并行	基于Mock 数据的 UI 插桩测试

三个设计上很聪明的点，值得学习：

智能触发：流水线会先比对 PR 的 diff，只有改动了app/、shared/、构建配置等路径时才触发插桩测试（pr.yml），文档类 PR 不用白等模拟器。
分片提速：插桩测试由 .github/scripts/run-instrumented-shard.sh 拆成 5 个分片并行跑在 5 台模拟器上，并以mock数据模式执行（不依赖真实账号），失败时自动抓取 logcat 诊断日志。
汇总门禁：最后一个 job android-instrument-tests 只校验各 job 结果——未触发插桩测试时要求状态为skipped，防止"该跑没跑"被误判为通过。

除此之外：

非 master 分支的每次 push 都会触发 Build Check，主干之外的代码也不会"裸奔"；
版本发布时，.github/release.yml 按标签把 changelog 自动归类为重大变化 / 🚀 新功能 / 🐛 Bug 修复三节。

本地测试策略建议

按项目沉淀的经验（CLAUDE.md）：本地不要默认跑完整 instrumented test（全量留给 CI），只做构建、格式化和针对当前失败点的定向用例，模拟器反馈更快；回归修复必须先"红到绿"——先在基线复现失败，修复后再确认变绿。

五、贡献规范：提交 PR 前必须知道的 5 件事

PR 标题与正文默认使用中文，这是项目约定，模板结构见 .github/PULL_REQUEST_TEMPLATE.md。
如实勾选 AI 使用声明：模板要求声明代码是否由 AI 编写/改写；若使用了 AI，必须附上实际运行产出的测试截图或录屏，设计图或旧截图不算数，否则不进入 review。
报 bug 用对模板：仓库提供 bug 反馈、功能建议与提问三类 issue 模板；bug 报告务必写清知乎++版本号和稳定复现步骤，缺版本的 issue 会被直接关闭。
feat 与 fix 按产品变化判定：新增用户可见的选项、入口或行为属于feat，只有既有承诺行为发生回归才属于fix——不要因为是"修 bug 改出来的"就把新功能归成修复。
遵守社区准则：项目采用 CODE_OF_CONDUCT.md（Contributor Covenant），营造无骚扰、包容的贡献环境。

六、延伸阅读：文档与周边工具

动手之前翻一翻这些目录，能少走很多弯路：

docs/：通知中心设计、Markdown 渲染性能报告、AI UI 设计指南
reports/：instrumented 测试失败的逐文件根因分析报告，排查 CI 失败的范本
misc/chrome-zhihu-ad-filter/：配套的浏览器广告过滤插件，含测试用例
aigc-vote-server/AGENTS.md：投票服务的运维与数据迁移注意事项

🚀 上手路线推荐：先git clone→./gradlew assembleLiteDebug装到手机跑一遍 → 读 README.md 的路线图 → 挑一个good first issue开始你的第一个 PR。祝你贡献顺利！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析