解决SeriesGuide 9大核心问题：从安装到同步全攻略

你还在为SeriesGuide同步失败抓狂？API密钥配置总是出错？备份恢复后数据丢失？本文汇总9个核心场景的解决方案，覆盖安装配置、数据同步、错误修复等关键问题，附代码示例和流程图，5分钟快速定位问题根源。读完你将掌握：

• 3步完成开发环境搭建（含API密钥配置）
• Trakt/Cloud同步失败的7种修复方案
• 数据备份与恢复的安全操作流程
• 崩溃问题的日志分析与版本回退技巧
• 通知不触发的底层权限配置方法

一、开发环境搭建问题

1.1 Android Studio导入项目失败

症状：导入后Gradle同步报错，提示"Plugin with id 'com.android.application' not found"。

解决方案：

1. 确认使用dev分支（最新开发版本）或main分支（稳定版）
2. 检查Android Studio版本是否≥Electric Eel（2022.1.1）
3. 执行以下命令修复依赖：

./gradlew clean build --refresh-dependencies

1.2 API密钥配置错误

症状：添加节目时提示"Could not add show"，日志显示401 Unauthorized。

解决方案： 在项目根目录创建secret.properties文件，添加：

SG_TMDB_API_KEY=你的TMDB密钥
SG_TRAKT_CLIENT_ID=你的Trakt客户端ID
SG_TRAKT_CLIENT_SECRET=你的Trakt客户端密钥

获取密钥步骤：

• TMDB：注册TMDB账号 → 创建API密钥（v3 Auth）
• Trakt：注册Trakt账号 → 创建应用（选择"TV Show"类型）

二、数据同步问题

2.1 Trakt反复要求重新连接

症状：频繁弹出"Connect Trakt"对话框，即使已登录。

解决方案：

1. 清除Trakt令牌缓存：

// 代码位置：com.battlelancer.seriesguide.trakt.TraktCredentials
TraktCredentials.getInstance(context).clear()
startActivity(AuthActivity.getIntent(context))

2. 检查系统时间是否同步（时区错误会导致OAuth令牌验证失败）
3. 升级至2025.1.2+版本（修复令牌刷新逻辑）

2.2 Cloud同步丢失剧集进度

症状：多设备同步后，已观看状态未正确同步。

解决方案：

1. 触发强制同步：

// 代码位置：com.battlelancer.seriesguide.sync.SgSyncAdapter
SyncUtils.triggerRefresh(SyncContract.CONTENT_URI_EPISODES)

2. 检查网络连接（需稳定网络完成全量同步）
3. 2025.2.5+版本修复了"云端重新添加已删除剧集"的问题

同步流程：

sequenceDiagram
    participant 设备A
    participant Cloud服务器
    participant 设备B
    设备A->>Cloud服务器: 上传观看记录(EPISODE_WATCHED事件)
    Cloud服务器-->>设备A: 确认接收(200 OK)
    设备B->>Cloud服务器: 轮询同步请求(30分钟间隔)
    Cloud服务器-->>设备B: 推送更新数据(增量同步)
    Note over 设备B: 更新本地数据库

三、数据备份与恢复

3.1 导出文件格式错误

症状：导入时提示"status_failed_file_access"或JSON解析错误。

解决方案：

1. 确保导出文件符合JSON Schema：

{
  "version": 2,
  "shows": [
    {
      "tmdb_id": 1399,
      "title": "Game of Thrones",
      "seasons": [
        {
          "season": 1,
          "episodes": [
            {
              "episode": 1,
              "watched": true,
              "watched_at": "2023-01-01T12:00:00Z"
            }
          ]
        }
      ]
    }
  ]
}

2. 使用"Export"功能（2025.2+版本重命名，原"Backup"）生成标准文件

3.2 恢复后数据冲突

症状：导入后剧集出现重复或状态异常。

解决方案：

1. 恢复前禁用Cloud/Trakt同步：

// 代码位置：com.battlelancer.seriesguide.settings.AdvancedSettingsFragment
preferences.edit().putBoolean("sync_enabled", false).apply()

2. 按以下步骤操作：
   • 导出当前数据（防止意外）
   • 清除应用数据（设置→应用→SeriesGuide→存储→清除数据）
   • 导入备份文件
   • 重新启用同步并选择"以本地数据为准"

四、常见错误与修复

4.1 "database_error"数据库错误

症状：操作时弹出"Could not modify data"，日志显示SQLiteConstraintException。

解决方案：

1. 检查Room数据库版本兼容性（schemas目录下版本需匹配）
2. 执行数据库修复：

adb shell am broadcast -a com.battlelancer.seriesguide.action.FIX_DATABASE

3. 若频繁发生，尝试降级至64.0.7版本（修复多个数据库约束问题）

4.2 "api_error_generic"网络错误

症状：加载内容时显示"Could not talk to TMDB"。

解决方案：

1. 检查API密钥有效性：

// 代码位置：com.battlelancer.seriesguide.tmdb.TmdbTools
if (BuildConfig.SG_TMDB_API_KEY.isEmpty()) {
    Log.e("TMDB", "API key missing")
}

2. 验证网络连接（需允许移动数据访问）
3. 切换DNS（推荐114.114.114.114，解决部分地区TMDB访问问题）

五、高级故障排除

5.1 生成调试日志

当遇到崩溃或未知错误时，启用调试日志：

1. 进入设置→高级→诊断→开启调试日志
2. 复现问题
3. 保存日志到文件：

adb pull /sdcard/Android/data/com.battlelancer.seriesguide/files/debug.log

日志包含网络请求、数据库操作和异常堆栈，可提交至GitHub Issues

5.2 版本回退指南

若新版本引入问题，可回退到稳定版本：

git checkout 2024.5.4  # 切换到指定版本
./gradlew installPureDebug  # 安装纯净版（无Google服务）

稳定版本推荐：

• 2024.5.4：修复Trakt同步和列表管理问题
• 2023.68.0.6：解决Android 14通知问题
• 2022.63.1.0：兼容性最好的旧版本（支持Android 5.0+）

六、通知配置问题

6.1 Android 13+通知不触发

症状：设置正常但收不到新剧集通知。

解决方案：

1. 检查精确闹钟权限：

// 代码位置：com.battlelancer.seriesguide.notifications.NotificationService
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    val alarmPermission = Manifest.permission.SCHEDULE_EXACT_ALARM
    if (ContextCompat.checkSelfPermission(context, alarmPermission) 
        != PackageManager.PERMISSION_GRANTED) {
        // 请求权限
    }
}

2. 确保通知渠道未被静音：
   • 设置→应用→SeriesGuide→通知→"新剧集"渠道→开启声音和振动

七、硬件与兼容性

7.1 低分辨率设备UI错乱

症状：控件重叠或文字截断（尤其在480x800屏幕）。

解决方案：

1. 使用兼容布局文件：

<!-- 位于res/layout-sw320dp/目录 -->
<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">
    <!-- 适配小屏幕的垂直布局 -->
</LinearLayout>

2. 升级至2025.2+版本（修复多屏幕尺寸适配问题）

八、Trakt集成问题

8.1 评论发布失败

症状：提示"shout_invalid"或"database_error"。

解决方案：

1. 确保评论符合要求：英文+5个以上单词
2. 检查Trakt API限制（每15分钟最多5条评论）
3. 2024.3+版本支持评论编辑/删除功能：

// 代码位置：com.battlelancer.seriesguide.traktapi.TraktComments
TraktV2.getInstance().comments().update(commentId, updatedComment)

九、性能优化

9.1 列表滚动卡顿

症状：剧集列表滑动掉帧（尤其在低端设备）。

解决方案：

1. 禁用图片缓存（设置→高级→"Images via Wi-Fi only"）
2. 减少列表项复杂度：

<!-- 优化前 -->
<ImageView
    android:layout_width="120dp"
    android:layout_height="180dp"
    android:scaleType="centerCrop"/>

<!-- 优化后 -->
<ImageView
    android:layout_width="80dp"
    android:layout_height="120dp"
    android:scaleType="centerCrop"
    tools:ignore="ContentDescription"/>

3. 使用RecyclerView优化技巧：

recyclerView.setHasFixedSize(true)
recyclerView.setItemViewCacheSize(20)

总结与后续

本文覆盖了SeriesGuide从开发环境到日常使用的核心问题。遇到新问题时，建议：

1. 检查CHANGELOG.md确认是否已修复
2. 尝试清除应用数据（设置→应用→清除数据）
3. 在官方论坛搜索解决方案

下期预告：《SeriesGuide高级技巧：自定义主题与扩展开发》，将介绍如何修改应用配色方案和开发第三方扩展。