简体中文

English

简体中文

English

外观

常见问题 ​

首次使用请先阅读快速开始，需要反馈时请附上日志和复现信息。

安装与启动 ​

应用无法启动 ​

先按安装指南确认安装包与操作系统、CPU 架构匹配，并记录启动时的错误提示。如果无法进入主界面，可直接按日志位置查找 app.log，提供脱敏日志和系统、应用版本等信息以便排查。日志文件不存在时，也请提供错误截图和安装包文件名。

Debian / Ubuntu 安装时的权限提示 ​

使用 sudo apt install ./安装包.deb 时，可能在末尾看到类似提示：

text
N: 由于文件 '…deb' 无法被用户 '_apt' 访问，已脱离沙盒并提权为根用户来进行下载。 - pkgAcquire::Run (13: 权限不够)

APT 获取软件包时会优先使用低权限用户 _apt，即使命令通过 sudo 执行也如此。如果安装包不可读，或用户主目录、桌面等上级目录不允许 _apt 进入，APT 会改用 root 读取本地文件。这条提示本身不代表安装失败，也不表示应用运行在沙盒之外。

先检查当前安装状态：

bash
dpkg -s res-downloader

输出包含 Status: install ok installed 时，表示当前已安装并配置完成；同时检查 Version: 是否为期望版本，无需仅因这条提示重复安装。若还有依赖不满足等错误，请根据完整输出排查。

如需避免权限提示，可将安装包复制到 _apt 能访问的目录并赋予读取权限后安装。以下以 4.0.0 的 amd64 安装包为例，请替换为实际路径、版本和架构：

bash
cp ~/Desktop/res-downloader_4.0.0_linux_amd64.deb /tmp/
chmod 644 /tmp/res-downloader_4.0.0_linux_amd64.deb
sudo apt install /tmp/res-downloader_4.0.0_linux_amd64.deb

无需放宽整个用户主目录的权限。sudo dpkg -i 不经过 APT 的软件包获取流程，因此不会出现这条 _apt 提示，但它也不会自动下载缺失依赖。推荐安装方式见Debian / Ubuntu 安装指南。

Windows 安装失败后如何重试 ​

首次安装因磁盘空间、文件占用或 WebView2 权限设置失败时，先解决错误提示中的原因，再运行安装包并选择同一目录。如果该目录有有效的安装记录或安装中断记录，安装器通过校验后即可继续安装，不必删除已经留下的文件。

如果目录非空且缺少有效记录，安装器无法确认其归属时会拒绝覆盖。请保留该目录，选择另一个空目录安装，或向 GitHub Issues 反馈；不要为绕过检查而删除整个目录。

Windows 无法卸载 ​

如果提示文件正在使用，请关闭软件或重启电脑后重试。如果提示安装记录无效，可下载最新版安装包，尝试覆盖安装到原目录后再卸载；若安装器拒绝该目录，请保留原目录并向 GitHub Issues 反馈错误提示，不要直接删除整个目录。

卸载会清理已记录的应用和固定版 WebView2 文件，保留下载、配置、插件及其他未知文件。不同 WebView2 安装包之间的切换方式见安装指南。

macOS 提示“已损坏，无法打开” ​

确认安装包来自项目官方发布页后，在“系统设置 → 隐私与安全性”中允许打开。仍无法打开时执行：

bash
sudo xattr -d com.apple.quarantine /Applications/res-downloader.app

检查更新失败后如何重试 ​

恢复网络后，在“系统设置 → 基础设置”中点击“检查更新”，无需重启应用。检查更新也遵循“下载代理”开关，启用时请确认上游代理可用。设置入口见基础设置。

若提示更新服务未提供有效的版本信息，可稍后重试或前往官网。需要反馈时，提供应用日志中的更新源错误；此类问题可能是服务器未提供有效清单，重置本地配置无法解决。

可以进入界面，但配置异常 ​

可在“系统设置 → 基础设置”中使用“清理缓存并重启”，并按提示授权。该操作会重置设置和证书，并清除抓取记录、任务历史等数据；完整清理范围见基础设置。确认可以接受这些数据被清理后再操作，已下载文件和已安装插件会保留。

资源抓取与网络 ​

某个网站或应用无法捕获 ​

按以下顺序检查：

  1. 在“获取资源”页面点击“开启抓取”，并确认已选择目标资源类型。
  2. 在“系统设置 → 证书”中确认当前设备证书已安装并受信任。
  3. 确认目标设备使用应用代理。本机默认代理为 127.0.0.1:8899；修改过监听地址或端口时，以“系统设置 → 高级设置”中的值为准，并重启应用。手机需单独接入。
  4. 检查目标域名是否被设为“直接透传”；此类连接不会被解密并捕获。
  5. 需要专用插件的网站，请确认对应插件已安装并启用，见插件管理。

完成检查后重新打开目标页面或播放内容。部分应用不支持代理抓取，即使代理和证书配置正确也可能无法捕获。

安装证书后仍提示未安装 ​

进入“系统设置 → 证书”，重新安装证书并刷新状态。Windows 请允许 UAC 授权；手机上的旧证书需要手动删除后重新安装。

手机如何接入 ​

  1. 手机和电脑连接同一网络。
  2. 将监听地址设为 0.0.0.0，重启应用并开启抓取。
  3. 手机代理填写电脑的局域网 IP 和应用端口。
  4. 在手机上下载安装当前证书并开启信任。

部分手机应用即使完成设置也可能无法捕获。

应用退出后无法上网 ​

应用正常退出时会关闭其管理的系统代理。如果进程异常退出，代理设置可能残留；请在系统网络设置中关闭 HTTP / HTTPS 代理，恢复联网后再重新启动应用。

开启抓取后 Reddit 无法正常访问 ​

如果开启抓取后 reddit.com 页面无法正常加载，可在“系统设置 → 高级设置 → TLS 拦截策略”中添加并启用以下策略：

配置项内容
策略名称*.reddit.com
处理方式直接透传
匹配域名分别添加 *.reddit.com 和 *.redditstatic.com
此策略内排除的域名留空

两个域名应分别添加为独立条目，不要用逗号合并成一个条目。将该策略放在通用“解密并捕获”策略之后；同一域名匹配多条策略时，后面的策略生效。

设置后重新打开 Reddit 页面，让新连接使用该策略。直接透传会保留这些域名的 HTTPS 加密连接，应用不再解密并捕获其内容。策略说明见 TLS 拦截策略。

视频号资源太多 ​

在“插件管理”中关闭微信视频号插件的“完整抓取模式”，清空列表后重新打开目标详情页。

资源过多提醒 ​

资源记录达到 1500 条时，软件提示资源较多、可能增加内存占用并影响运行稳定性；此后每增加 500 条再次提醒。数量包含合集子资源，不受当前分页、筛选或展开状态影响。启动恢复和导入资源也会检查数量，一批资源跨过多个阈值只提醒一次。

提醒不代表已经检测到内存不足，也不会自动清理资源。可使用资源列表现有的清理入口删除不再需要的资源；清理后按剩余数量重新计算下一次提醒阈值。

下载与媒体处理 ​

HLS / M3U8 视频如何预览和下载 ​

可直接在资源列表中预览和下载。内置 HLS 下载支持相对分片地址、Master Playlist、AES-128 加密分片，并使用抓取到的请求头。

内置 HLS 分片下载不需要 FFmpeg；如果插件使用 FFmpeg 下载，或下载后需要合并音视频、转封装，则需先配置 FFmpeg。下载失败时，先重新抓取资源，确认链接未过期，再检查下载代理和请求头设置。

直播如何预览和录制 ​

HLS / FLV 直播可直接预览。录制前需自行安装 FFmpeg，并在“系统设置 → 媒体处理”中完成检测；软件不内置 FFmpeg。

录制结束时，在任务上点击“停止并保存”以保存已录制内容。

直播录制无法使用 ​

在“系统设置 → 媒体处理”中点击“检测 FFmpeg”，确认 FFmpeg 和 FFprobe 均显示“可用”。自动检测不到时，可分别选择实际可执行文件；安装程序或修改系统 PATH 后，需要重启应用再检测。详细步骤见媒体处理。

微信视频号加密文件如何处理 ​

使用软件内置下载时，会自动执行微信视频号插件的处理链，无需手动解密。

如果通过复制链接和其他工具下载了加密文件，可在对应资源的操作菜单中选择“解密本地视频”，再选择该本地文件。请使用与文件对应的资源记录。

下载慢或大文件失败 ​

检查保存空间、链接是否过期和下载代理是否可用。视频号链接过期时需要重新抓取。

下载提示 filename template error ​

到“系统设置 → 基础设置”检查文件命名模板。模板需要生成保存目录内的相对路径，不能以 / 或盘符开头，也不能包含 .. 上级目录。设置时会拒绝可提前确定的错误，并在输入框下显示原因；资源标题或插件元数据只有下载时才能确定，仍可能生成不安全的路径。对标题、作者等变量使用 sanitize，必要时添加 default，写法见文件命名模板。

如果模板看起来正确但仍报错，请提供完整错误、操作系统、保存目录、模板和资源标题，并先隐藏其中的私人信息。

下载后的文件名变成 resource-开头 ​

软件会先使用文件命名模板生成目标名称，并自动清理不兼容符号和过长名称。如果操作系统仍拒绝该名称，下载完成后的安装步骤会改用 resource-<短标识>.扩展名 保存，避免丢弃已经下载和处理的数据。实际保存路径以任务中心显示为准；两次安装都失败时，临时输出会保留在当前保存目录的 .res-downloader-work 中，并可通过删除失败任务、清理已结束任务或“清理缓存并重启”删除。如需排查原名称被拒绝的原因，请提供脱敏后的日志。

连接与问题反馈 ​

CLI 或 MCP 无法连接 ​

CLI 和 MCP 需要更新后的桌面应用保持运行，并与应用使用同一操作系统用户。连接文件不可用、会话失效、Agent 沙箱权限或资源列表为空等问题，请查看 CLI 与 MCP：连接与排查。

如何查看软件日志 ​

正式版会把运行日志写入 app.log。如果应用可以进入主界面，可在“系统设置 → 基础设置”中点击“打开日志目录”。请先复现问题并退出应用，再复制日志文件用于排查。

Windows ​

日志路径：

text
%APPDATA%\res-downloader\logs\app.log

按 Win + R，输入 %APPDATA%\res-downloader\logs 并回车，即可在资源管理器中打开日志目录。也可以在 PowerShell 中查看最后 200 行：

powershell
Get-Content "$env:APPDATA\res-downloader\logs\app.log" -Tail 200

macOS ​

日志路径：

text
~/Library/Preferences/res-downloader/logs/app.log

在访达中按 Command + Shift + G，输入 ~/Library/Preferences/res-downloader/logs 并回车。也可以通过终端打开日志目录或查看最后 200 行：

bash
open ~/Library/Preferences/res-downloader/logs
tail -n 200 ~/Library/Preferences/res-downloader/logs/app.log

Linux ​

默认日志路径：

text
~/.config/res-downloader/logs/app.log

如果设置了 XDG_CONFIG_HOME，日志会保存在 $XDG_CONFIG_HOME/res-downloader/logs/app.log。可以在终端查看最后 200 行：

bash
tail -n 200 "${XDG_CONFIG_HOME:-$HOME/.config}/res-downloader/logs/app.log"

如果日志目录或 app.log 不存在，应用可能在日志系统初始化前就已退出。反馈问题时请同时提供操作系统版本、系统架构、应用版本、安装包文件名、复现步骤和截图。

提交日志前请先检查并隐藏其中可能出现的账号、Cookie、Token、资源地址、本地用户名和文件路径等隐私信息。

仍然无法解决 ​

请前往 GitHub Issues 反馈，并附上系统、应用版本、复现步骤和错误信息。请先隐藏账号、Cookie 等隐私数据。

业务操作不可用或结果缺失 ​

  • 页面未连接或未就绪：开启抓取并启用插件，刷新浏览器中的目标网页，等待内容加载并按需登录。多个页面时选择正确的目标；刷新软件界面无法重新连接网页。
  • 执行中断或结果不确定：先检查关联资源和下载任务，再决定是否重新提交。
  • 历史存在但结果缺失：结果可能已过期、被清理，或未在重启后保留；需要时重新执行。
  • 存储不可用：检查用户配置目录权限和磁盘空间，再重新启动应用。
  • 产物不可读：确认下载已完成，文件未被移动、删除或清理。

自动化使用方法见 CLI 与 MCP。

请确保对所处理的资源拥有合法权利，并遵守所在地法律、平台协议和版权规定。

res-downloader · Windows / macOS / Linux