贡献指南

本文档提供了创建新 Tachiyomi 扩展的说明和技巧。如果您是首次贡献者或对所需语言和技术缺乏经验，请仔细阅读。

本指南并非最终版，会持续更新。如果您发现任何问题，欢迎通过元问题（Meta Issue）报告，或直接提交 Pull Request 修复。

前提条件

开始前请注意，以下技术的使用能力是必需的，现有贡献者不会主动教授这些知识：

工具

Android Studio
已启用开发者选项的模拟器或手机，并安装最新版 Tachiyomi
图标生成器

克隆仓库

若仓库过大且包含大量源，可执行以下步骤跳过无关内容，加快克隆、导航和构建速度。此方法也可减少磁盘占用和网络流量。

仅当仓库巨大且包含大量源时需执行这些步骤。若仓库较小，请直接完整克隆。

步骤

执行部分克隆：

git clone --filter=blob:none --sparse <fork-repo-url>
cd extensions-source/

配置稀疏检出（Sparse Checkout）：

有两种模式：默认的锥形（🔺）模式和非锥形模式。锥形模式在大仓库中匹配更快，但灵活性较低。若需简单过滤，可跳过锥形模式。

锥形模式：

git sparse-checkout set --cone --sparse-index
# 添加项目目录
git sparse-checkout add buildSrc core gradle lib lib-multisrc utils
# 添加单个源
git sparse-checkout add src/<lang>/<source>

非锥形模式：

git sparse-checkout set --no-cone
# 编辑过滤规则（示例）
/*
!/src/*
!/multisrc-lib/*
/src/<lang>/<source>
/lib-multisrc/<source>

配置远程仓库：

git remote add upstream <keiyoushi-repo-url>
git remote set-url --push upstream no_pushing
git config remote.upstream.fetch "+refs/heads/main:refs/remotes/upstream/main"
git remote update
git branch main -u upstream/main

可选实用配置：

git config remote.origin.prune true
git config pull.ff only
git config alias.sync-main '!git switch main && git fetch upstream && git reset --keep FETCH_HEAD'

若修改稀疏检出规则，运行：
```
git sparse-checkout reapply
```

详情参阅 Git 文档。

获取帮助

加入 Discord 服务器的 #programming 频道提问。
参考现有扩展代码示例，部分功能未在本文档中提及。

编写扩展

建议复制现有扩展的目录结构并按需重命名。开始前请阅读现有扩展代码。

设置新的 Gradle 模块

每个扩展应位于 src/<lang>/<mysourcename>。若源支持多语言，使用 all 作为 <lang>。

文件夹中的 <lang> 应为主要语言代码（如 pt-BR 对应 pt），源类中使用完整区域代码。

加载部分 Gradle 模块

默认加载所有扩展，若需仅加载部分，调整 settings.gradle.kts 文件。

扩展文件结构

基本结构示例：

src/<lang>/<mysourcename>/
├── AndroidManifest.xml (可选)
├── build.gradle
├── res
│   └── ...（图标）
└── src
    └── eu
        └── kanade
            └── tachiyomi
                └── extension
                    └── <lang>
                        └── <mysourcename>
                            └── <MySourceName>.kt

包名必须为 eu.kanade.tachiyomi.extension.<lang>.<mysourcename>。

build.gradle 结构

ext {
    extName = '<源名称>'
    extClass = '.<主类名>'
    extVersionCode = 1
    isNsfw = true
}

apply from: "$rootDir/common.gradle"

字段	说明
`extName`	扩展名称，非英文需罗马化
`extClass`	实现 `Source` 的类路径（以点开头）
`extVersionCode`	版本号，每次代码变更需递增
`isNsfw`	（可选）标记是否包含 NSFW 内容，默认 `false`

版本名自动生成（如 1.4.1）。

核心依赖

扩展 API

依赖 extensions-lib，实际实现参考主应用代码。

其他库

lib-dataimage：处理 Base64 图片数据。
lib-i18n：国际化支持，加载 assets/i18n 下的翻译文件。

添加依赖示例：

dependencies {
    implementation(project(':lib-dataimage'))
    implementation(project(':lib-i18n'))
}

扩展主类

主类需实现 SourceFactory 或继承 HttpSource/ParsedHttpSource。

类	说明
`SourceFactory`	暴露多个源（如多语言/镜像）
`HttpSource`	基于 HTTP 的在线源
`ParsedHttpSource`	支持网页抓取的工具类

关键字段

字段	说明
`name`	在“来源”列表中显示的名称
`baseUrl`	基础 URL（不带末尾斜杠）
`lang`	ISO 639-1 语言代码
`id`	源标识符，通常自动生成

扩展调用流程

漫画搜索（Manga Search）

fetchSearchManga 处理搜索请求，支持过滤器。
过滤器类型包括选择框、文本输入、排序等。

漫画详情（Manga Details）

用户点击漫画时调用 getMangaDetails 和 getChapterList。
SManga 通过 url 标识。
章节列表需按源顺序降序排列。

高级功能

URL 意图过滤器

通过 AndroidManifest.xml 添加深度链接支持。测试命令：

adb shell am start -d "<链接>" -a android.intent.action.VIEW

更新策略

UpdateStrategy.ALWAYS_UPDATE：默认，始终更新。
UpdateStrategy.ONLY_FETCH_ONCE：仅首次获取，适用于完结作品。

重命名现有源

需保持 id 不变以避免用户迁移。示例：

override val id: Long = <旧ID>

多源主题

multisrc 模块用于生成基于相同 CMS 的多个源。目录结构：

multisrc
├── overrides
│   └── <主题包>
│       ├── default      # 默认图标和配置
│       └── <源包>       # 单个源的覆盖文件
└── src
    └── main
        └── java         # 主题默认实现和生成器

开发流程

生成代码：
- 运行主题生成器或执行 ./gradlew multisrc:generateExtensions。
同步 Gradle：导入生成的模块。
测试扩展：与普通扩展相同。

运行

在 Android Studio 中使用以下配置直接启动到“浏览”界面：

调试版命令：

-W -S -n eu.kanade.tachiyomi.debug/eu.kanade.tachiyomi.ui.main.MainActivity -a eu.kanade.tachiyomi.SHOW_CATALOGUES

调试

Android 调试器

使用 Attach Debugger to Android Process 附加到 Tachiyomi 进程。

日志

通过 Android Studio 的 Logcat 面板查看日志，过滤 OkHttpClient 标签。

网络检查

启用详细日志（设置 → 高级 → 详细日志）后，可通过以下方式检查请求：

内置网络分析器：使用 Android Studio 的 Network Inspector。
mitm-proxy：设置代理并禁用 SSL 验证（示例代码见文档）。

构建

通过 Android Studio 生成 APK，或命令行：

./gradlew src:<lang>:<source>:assembleDebug

提交更改

提交 Pull Request 前请确保：

更新 extVersionCode 或 overrideVersionCode。
引用相关 Issue（如 Closes #xyz）。
测试修改后的扩展。
移除自动生成的 web_hi_res_512.png。

Pull Request 检查清单

更新单源的更新单源的 `extVersionCode`
更新多源的 overrideVersionCode 或更新多源的 `overrideVersionCode` 或 `baseVersionCode`
关联所有相关 Issue
标记 isNsfw 标记 `isNsfw`（如适用）
未修改源名称
保留重命名源的保留重命名源的 `id`
通过 Android Studio 编译测试
移除新扩展的移除新扩展的 `web_hi_res_512.png`

Hualiang's Blog

目录