Folo 故障排除完全指南

应用启动与安装问题

应用无法启动或闪退

用户场景：双击应用图标后无反应，或启动后立即关闭，无错误提示。

问题现象描述

应用启动过程中断，可能伴随系统错误提示或无任何反馈直接退出。

可能原因分析

• 系统资源不足或后台进程冲突
• 应用文件损坏或不完整
• 系统版本与应用不兼容
• 配置文件损坏或权限问题

分步解决方案

基础方法：重启与检查系统要求

🔍 检查系统兼容性

• 确认您的操作系统版本符合要求：
  • Windows: Windows 10 1809或更高版本
  • macOS: macOS 10.15 (Catalina)或更高版本
  • Linux: Ubuntu 18.04/Debian 10或更高版本

▶️ 执行重启

# Windows用户
shutdown /r /t 0

# macOS/Linux用户
sudo reboot

进阶方法：清除应用缓存

⚙️ 定位缓存目录

# Windows
%APPDATA%\Folo\cache

# macOS
~/Library/Caches/is.follow/

# Linux
~/.config/Folo/cache

▶️ 清除缓存文件

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\Folo\cache"

# macOS/Linux
rm -rf ~/Library/Caches/is.follow/*  # macOS
# 或
rm -rf ~/.config/Folo/cache/*        # Linux

替代方案：重新安装应用

▶️ 卸载现有版本

# macOS示例
rm -rf /Applications/Folo.app

▶️ 克隆仓库并安装

git clone https://gitcode.com/GitHub_Trending/fol/follow
cd follow
pnpm install
pnpm build
pnpm package

验证方法

启动应用后观察：

• 应用是否成功进入主界面
• 检查关于页面确认版本号
• 观察5分钟确认是否稳定运行

预防措施

• 定期通过官方渠道更新应用
• 避免强制关闭应用进程
• 保持系统有至少2GB可用内存
• 定期清理应用缓存

[!NOTE] 如果问题反复出现，请收集应用日志并提交issue。日志文件路径：~/.config/Folo/logs/main.log

安装过程中出现"应用已损坏"提示

用户场景：macOS用户在安装时看到"Folo已损坏，无法打开"的安全提示。

问题现象描述

系统安全机制阻止应用安装，提示应用来源不明或文件已损坏。

可能原因分析

• 应用未经过Apple公证
• 系统安全设置限制
• 下载过程中文件损坏
• 磁盘权限问题

分步解决方案

基础方法：调整安全设置

🔍 打开系统设置

open -a "System Preferences" && open "x-apple.systempreferences:com.apple.preference.security"

⚙️ 允许应用运行

1. 在"安全性与隐私"中点击"仍要打开"
2. 输入管理员密码确认

进阶方法：使用终端绕过安全检查

▶️ 执行以下命令

sudo xattr -rd com.apple.quarantine /Applications/Folo.app

替代方案：从源码构建

▶️ 克隆并构建项目

git clone https://gitcode.com/GitHub_Trending/fol/follow
cd follow/apps/desktop
pnpm install
pnpm make

验证方法

成功启动应用并检查"关于"窗口，确认版本信息正确显示。

预防措施

• 从官方渠道下载应用
• 定期更新系统以获取最新安全补丁
• 构建前验证Git仓库完整性：git verify-commit HEAD

数据同步与订阅问题

订阅源无法添加或同步失败

用户场景：尝试添加RSS订阅时提示"无效URL"，或订阅后无法获取内容更新。

问题现象描述

添加订阅源时失败，或已添加的源长时间不更新，同步状态显示错误。

可能原因分析

• URL格式错误或源地址已变更
• 网络连接问题或代理配置错误
• 源服务器设置了访问限制
• 应用同步服务未正常运行

分步解决方案

基础方法：验证URL与网络

🔍 检查URL格式 确保URL以http://或https://开头，且能在浏览器中正常访问。

▶️ 测试网络连接

# 测试网络连通性
ping -c 4 feed.example.com

# 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

进阶方法：手动同步与日志检查

⚙️ 触发手动同步 通过应用内"设置 > 内容 > 立即同步"执行手动同步

▶️ 检查同步日志

# 查看同步服务日志
tail -n 100 ~/.config/Folo/logs/sync-service.log

替代方案：手动导入OPML文件

1. 从源网站下载OPML文件
2. 通过"文件 > 导入订阅 > OPML文件"导入

验证方法

添加测试订阅源https://example.com/feed，确认能正常获取内容。

预防措施

• 使用应用内置的订阅发现功能
• 定期备份订阅列表：文件 > 导出订阅
• 检查packages/internal/database/src/services/subscription.ts了解订阅机制

界面与显示问题

界面显示异常或文字乱码

用户场景：应用界面元素错位、文字重叠或显示乱码字符。

问题现象描述

界面布局错乱，文字显示不完整或出现方框等替代字符，图标显示异常。

可能原因分析

• 字体文件缺失或损坏
• 显示缩放比例设置不当
• 图形渲染引擎问题
• 界面配置文件损坏

分步解决方案

基础方法：重置界面设置

⚙️ 恢复默认界面设置

1. 打开"设置 > 外观 > 恢复默认设置"
2. 重启应用

▶️ 清除字体缓存

# Windows
del %LOCALAPPDATA%\Folo\font-cache.dat

# macOS
rm ~/Library/Caches/is.follow/font-cache.dat

# Linux
rm ~/.config/Folo/font-cache.dat

进阶方法：手动指定系统字体

⚙️ 修改字体配置 编辑配置文件：~/.config/Folo/config.json

{
  "appearance": {
    "fontFamily": "system-ui, -apple-system, sans-serif",
    "fontSize": 14
  }
}

替代方案：重新安装应用资源

▶️ 重新构建前端资源

cd follow
pnpm run build:renderer

验证方法

检查界面文字是否清晰，布局是否正常，特别注意中文、日文等非英文字符显示。

预防措施

• 避免修改应用安装目录下的资源文件
• 保持系统字体库完整
• 定期执行scripts/update-icon.ts更新资源

AI功能问题

AI摘要或翻译功能无法使用

用户场景：点击"AI摘要"按钮无反应，或翻译功能返回错误信息。

问题现象描述

AI相关功能无法触发，或提示"服务不可用"、"API密钥无效"等错误。

可能原因分析

• API密钥未配置或已过期
• 网络连接问题或防火墙限制
• AI服务暂时不可用
• 功能模块未正确加载

分步解决方案

基础方法：检查API配置

⚙️ 验证API密钥

1. 打开"设置 > AI功能 > API服务"
2. 确认API密钥已正确输入且未过期
3. 点击"测试连接"验证服务可用性

▶️ 检查网络连接

# 测试AI服务连接
curl -I https://api.follow.is/v1/ai/summary

进阶方法：查看AI服务日志

▶️ 检查服务状态

# 查看AI服务日志
tail -n 50 ~/.config/Folo/logs/ai-service.log

# 检查服务进程
ps aux | grep ai-service

替代方案：切换AI服务提供商

⚙️ 更改AI服务配置

1. 打开"设置 > AI功能 > 服务提供商"
2. 选择其他可用的AI服务
3. 重新配置对应服务的API密钥

验证方法

使用"帮助 > 测试AI功能"执行内置测试，确认能正常生成摘要和翻译文本。

预防措施

• 定期检查API密钥有效期
• 保持网络稳定，避免频繁切换网络环境
• 关注packages/internal/services/ai/的更新日志

问题反馈模板

如果您遇到了本指南未涵盖的问题，请使用以下模板提交反馈：

### 问题描述
[简要描述问题现象]

### 复现步骤
1. [第一步操作]
2. [第二步操作]
3. [观察到的结果]

### 环境信息
- 操作系统: [例如: Windows 11 22H2]
- 应用版本: [例如: 1.3.0]
- 安装来源: [官方网站/GitHub/其他]

### 附加信息
- [是否有错误提示截图]
- [相关日志文件内容]
- [其他补充说明]

请将填写好的模板提交至项目的issue跟踪系统或发送至[e-mail]。