Folo应用故障排除指南：从诊断到解决

安装与启动问题

应用无法安装（Windows）

症状诊断

Windows系统下出现"无法验证发布者"或"应用已损坏"错误提示，导致安装程序无法正常运行。

解决方案

1. 右键安装文件，选择"属性"
2. 在"常规"选项卡中勾选"解除锁定"
3. 以管理员身份运行安装程序

若问题持续，尝试命令行安装：

cd C:\path\to\installer
.\Folo-Setup.exe --install --force

技术原理

Windows系统对未签名应用有严格安全限制，需要手动解除锁定并赋予管理员权限。

常见用户误区：认为"解除锁定"会降低系统安全性，实际上这只是针对单个文件的临时授权，不会影响整体系统安全。

相关安装脚本：scripts/run-proxy.sh

启动后立即崩溃（macOS）

症状诊断

应用启动后立即退出，无明显错误提示或仅短暂显示启动窗口后消失。

解决方案

1. 确认macOS版本符合要求（需10.15或更高版本）
2. 前往"系统设置 > 隐私与安全性"检查Folo的文件访问权限
3. 清除应用缓存：

rm -rf ~/Library/Caches/is.follow

技术原理

macOS的应用沙箱机制限制了应用对系统资源的访问，权限不足或缓存损坏会导致应用异常退出。

常见用户误区：频繁重装应用而不清除缓存，导致问题反复出现。清除缓存是解决大多数启动问题的关键步骤。

官方兼容性说明：README.md

内容同步与订阅问题

订阅源无法添加

症状诊断

添加RSS或Atom订阅源时提示"无效URL"或"连接失败"，但URL在浏览器中可正常访问。

解决方案

1. 验证URL格式，确保以http://或https://开头
2. 检查网络连接和防火墙设置
3. 在设置中配置代理或认证信息（如有需要）
4. 使用在线RSS验证工具检查源格式是否标准

技术原理

订阅功能需要严格遵循RSS/Atom协议标准，任何格式错误或网络障碍都会导致订阅失败。

常见用户误区：将网站首页URL当作订阅源URL，正确的订阅源通常以.xml结尾或在页面中有专门的RSS图标链接。

订阅功能实现代码：packages/internal/database/src/services/subscription.ts

内容同步不及时

症状诊断

已订阅的源更新后，Folo长时间未显示新内容，或同步进度停滞。

解决方案

1. 点击工具栏中的刷新按钮手动触发同步
2. 检查"设置 > 内容 > 同步频率"配置
3. 清除同步缓存："设置 > 高级 > 清除缓存 > 仅同步缓存"
4. 验证网络连接稳定性

技术原理

Folo采用增量同步机制，依赖定时任务和服务器响应，网络波动或缓存异常会导致同步延迟。

常见用户误区：认为同步频率设置越高越好，实际上过高的同步频率可能导致服务器限制或网络流量过大。

同步服务代码：packages/internal/services/sync.ts

界面与显示问题

界面文字乱码或显示异常

症状诊断

应用界面出现文字重叠、乱码或图标显示不正常，影响正常使用。

解决方案

1. 重置界面设置："设置 > 外观 > 恢复默认设置"
2. 更换字体："设置 > 外观 > 字体 > 选择系统字体"
3. 调整缩放比例："设置 > 显示 > 缩放"
4. 清除字体缓存：

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

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

技术原理

界面渲染依赖字体文件和CSS样式表，字体缺失或样式冲突会导致显示异常。

常见用户误区：安装过多自定义字体导致字体渲染冲突，建议只保留常用系统字体。

界面布局代码：apps/desktop/layer/renderer/src/components/layout/

深色模式切换异常

症状诊断

无法切换深色/浅色模式，或切换后部分界面元素颜色不匹配。

解决方案

1. 手动选择主题："设置 > 外观 > 主题 > 手动选择"
2. 检查系统主题设置是否与应用冲突
3. 清除主题缓存："设置 > 高级 > 清除缓存 > 主题缓存"

技术原理

应用主题系统基于CSS变量实现，系统主题与应用主题冲突会导致显示异常。

常见用户误区：频繁切换主题导致缓存混乱，建议确定一种主题后保持使用。

主题实现代码：apps/desktop/layer/renderer/src/theme/

AI功能问题

AI摘要无法生成

症状诊断

点击"AI摘要"按钮后无反应，或提示"无法连接到AI服务"。

解决方案

1. 检查网络连接状态
2. 确认"设置 > AI功能 > 启用AI摘要"已开启
3. 检查API密钥配置："设置 > AI功能 > API密钥"
4. 访问服务状态页面确认AI服务是否正常运行

技术原理

AI摘要功能依赖云端API服务，需要网络连接和有效API密钥授权。

常见用户误区：认为AI功能可以离线使用，实际上所有AI功能都需要联网访问云端服务。

AI功能实现代码：packages/internal/services/ai/

翻译功能不准确或无响应

症状诊断

翻译结果错误、不完整或翻译功能完全无响应。

解决方案

1. 确认选择了正确的源语言和目标语言
2. 尝试分段翻译长文本
3. 检查网络连接状态
4. 切换翻译引擎："设置 > AI功能 > 翻译引擎"

技术原理

翻译功能基于第三方API实现，翻译质量和响应速度受网络状况和API服务影响。

常见用户误区：期望AI翻译达到专业人工翻译水平，实际AI翻译结果需要人工校对，特别是专业领域内容。

翻译服务代码：apps/mobile/src/lib/translation.ts

问题反馈模板

当您遇到无法解决的问题需要官方支持时，请提供以下信息：

基本信息

• 应用版本：（在"设置 > 关于"中查看）
• 操作系统及版本：
• 安装方式：（官网下载/应用商店/其他）

问题描述

• 问题发生时间：
• 问题复现步骤：

错误信息

• 错误提示内容：
• 截图或录屏：（如有）

系统信息

• 网络环境：（家庭网络/公司网络/公共Wi-Fi）
• 防火墙或安全软件：（如有）

附加信息

• 问题发生前的操作：
• 是否尝试过上述解决方案：（是/否，具体说明）
• 其他相关信息：

请将上述信息发送至[e-mail]获取技术支持。

高级故障排除

收集日志用于问题报告

症状诊断

需要向官方报告复杂问题，需要提供详细日志文件。

解决方案

1. 打开"设置 > 高级 > 开发者选项"
2. 开启"详细日志记录"
3. 重现问题
4. 点击"导出日志"
5. 将生成的日志文件发送至[e-mail]

技术原理

日志文件记录了应用运行时的详细信息，有助于开发团队定位问题根源。

常见用户误区：担心日志包含隐私信息，实际上Folo日志仅记录应用运行状态，不包含个人数据。

日志配置文件：packages/internal/logger/

手动更新应用

症状诊断

自动更新失败或需要立即使用最新版本功能。

解决方案

1. 访问官方下载页面获取最新安装包
2. 关闭正在运行的Folo应用
3. 运行新的安装程序，选择"覆盖安装"
4. 启动应用后验证版本号："设置 > 关于 > 版本信息"

技术原理

手动更新绕过自动更新机制，直接替换应用文件，解决更新服务器连接问题。

常见用户误区：更新前未完全关闭应用，导致文件替换失败。确保任务管理器中没有Folo相关进程运行。

更新脚本：scripts/update-app.sh