更新与故障排查
本页快捷入口：检查更新 · 证书错误 · 转换器与样式 · 网页抓取 · 未知同步数据 · 运行 JavaScript · 文件名错误
检查更新
“帮助”菜单提供“检查更新”。当前更新流程包含版本检查、更新包下载、完整性验证和分平台安装提示。
更新前建议：
- 等待当前同步结束。
- 备份红豆数据目录。
- 记录关键插件和自定义设置。
- 关闭正在使用红豆引文插件的文档。
常规排查顺序
- 重启红豆并复现问题。
- 检查网络、账号登录、同步和附件状态。
- 确认系统时间、磁盘空间和文件访问权限。
- 停用最近安装或更新的第三方插件。
- 仍未解决时，通过“帮助 → 意见反馈”提供复现步骤。
- 支持人员要求日志时，按本页的调试模式说明收集。
常见场景
应用无法启动或界面异常：记录启动时的提示和近期插件变更。能进入应用时，先停用最近新增或更新的插件；仍无法恢复时，按支持人员指导使用本页的调试启动与故障排除模式。
在线检索或智问不可用：检查红豆登录、网络和服务权益；第三方来源还要分别检查官网会话、访问验证与全文订阅权限。明确提示红豆会话失效时重新登录原账号，网络或限流错误无需清空文库。专利来源跳过与“无结果”不同，应先查看检索详情。
自动更新元数据没有补充：先区分没有变化、缺少识别信息、需要人工核对与来源异常；受保护或手工清空的字段不会反复自动补回。批量处理中未可靠确认的条目可单独重试，详见元数据编辑。
附件打不开：确认文件已下载、本地路径可访问，并检查附件同步设置。
导入后附件缺失：确认原附件文件仍存在，且导出文件中记录的路径有效。
第三方插件不显示：确认插件兼容当前红豆版本，重新安装后重启红豆。
反馈问题
记录红豆版本、操作系统、复现步骤、预期结果、实际结果和发生时间。截图应遮盖私人文献、账号、验证码和服务器密码；日志发送前也应检查隐私内容。
高级用户可按实际提供的入口使用错误控制台、运行 JavaScript、运行 SQL、样式编辑器和转换器编辑器；调试日志入口需要调试模式。运行 SQL 或脚本可能直接修改本地数据库，操作前必须备份。
SSL／证书与网络错误
先记录出错服务和完整错误代码，检查系统日期、时间、时区，然后重启应用。用浏览器访问同一个服务地址，比较是否也报证书或连接错误。代理、机构网络、HTTPS 检查软件以及 WebDAV 服务器证书链不完整都可能影响连接。
浏览器可访问不一定表示应用使用相同代理或信任设置。机构网络有专用证书时，请让 IT 管理员核对可信证书与代理配置；WebDAV 出错时请服务商修正域名、证书有效期和完整证书链。不要通过关闭证书验证来解决，也不要在不安全的连接中反复输入账号密码。
转换器或引用样式无法加载
公共样式仓库的登录失效、无权限、网络异常与无搜索结果，不等于本地样式损坏。先按提示重新登录原账号或重试，本地已安装样式仍可使用。
转换器或本地样式加载的启动错误可能使导入、网页抓取和引用功能无法工作。先确认磁盘空间和数据目录读写权限，退出后备份整个目录。再在“设置 → 高级 → 文件和文件夹”中检查数据库完整性，并按需要重置转换器或样式。
重置可能恢复内置文件或影响自定义内容，先备份自定义转换器和 CSL 样式。若重置无效，保留错误原文和日志，不要直接清空整个数据目录。主数据库问题见损坏恢复。
网页或在线来源抓取失败
确认能在同一网络正常打开原文页面、已完成必要的机构登录，页面已加载完成。只有一个来源失败时，常见原因是网站布局变更、访问限制或没有对应转换器；多个来源都失败时，优先检查网络和转换器加载状态。
尝试使用 DOI／ISBN 等标识符添加，或从来源网站导出 RIS／BibTeX 再导入，附件可单独添加。记录失败页面的网址、尝试的入口和错误提示；不要反复高频请求受限网站。网站检索结果和可下载全文是不同权限，成功导入题录不代表一定能获取 PDF。
同步出现未知数据错误
先将所有参与同步的设备更新到兼容的红豆版本并重启，再确认使用同一账号。若仍出错，停止在多台设备上继续修改同一批数据，保存本地备份，并记录错误原文、发生时间和设备版本。不要手动删除未知字段或循环执行覆盖重置。
测试版本与开发构建
测试版本用于验证新功能，可能出现兼容性或数据库升级变化。使用真实文库前先备份；需要隔离测试时使用独立的数据目录。不要让测试版本与旧正式版本交替打开同一个文库。回退兼容性见数据库版本说明。
版本号与更新说明
在“帮助 → 关于”确认实际安装版本，在“帮助 → 检查更新”查看当前可用更新及提示。安装包和版本公告以红豆产品下载页及官方反馈区为准。手册说明功能和操作，不以旧截图中的版本号作为当前发布版本。
运行 JavaScript 与开发排错
“工具 → 开发者 → 运行 JavaScript”在应用内部执行脚本，可访问底层 Zotero 命名空间和本地文库。名称沿用底层架构；并非在普通浏览器网页中执行。
只查询版本的示例：
return Zotero.appVersion;在需要 await 的脚本中启用异步运行。写入条目应遵循数据对象保存与数据库事务规则。运行未知脚本可能修改或删除文库，先阅读脚本并备份；反馈问题优先提供复现步骤和错误日志，而不是在真实文库中尝试来源不明的修复脚本。
不能创建附件文件或文件名过长
确认磁盘有可用空间、数据目录可写、文件未被外部程序锁定。如果使用带文件名加密的文件系统，实际允许的文件名长度可能比普通文件系统短；中文字符也可能占用更多字节。可在文件重命名模板中减少题名长度，先用少量附件测试。
如果只是某个文件名失败，检查非法字符和路径长度；所有附件都无法创建时，优先检查目录权限和磁盘。不要为解决附件文件名问题修改数据库内部路径。
应用内意见反馈
当前可通过 帮助 → 意见反馈 提交问题。在描述中写明红豆版本、系统、触发步骤、期望结果与实际提示；能附上对应界面截图时，先遮盖账号、文献或路径中不需要展示的信息。
反馈应区分题录同步、附件下载、向量索引同步、来源网站登录和第三方插件问题。先保留现场与备份，必要时附对应的错误编号或调试输出；不要通过反复覆盖同步或清空文库来获取新的错误记录。
故障排除模式、错误报告与调试输出
常规问题先用 帮助 → 意见反馈 提供复现步骤。当前普通启动时，帮助菜单不会显示“报告错误”“调试日志”和“以故障排除模式重启…”；这些入口只在调试模式下显示。意见反馈不会自动附上完整调试日志。
如果支持人员要求诊断日志，先保存文档并退出红豆，再按其指导从当前安装的应用可执行文件添加 -ZoteroDebug 或 -ZoteroDebugText 参数启动。可执行文件的位置与启动方式随系统和安装目录不同，使用当前安装路径；启动后核对帮助菜单中的诊断入口。
在调试模式中，帮助 → 以故障排除模式重启… 可临时禁用插件。先保存当前文档、核对重启提示，再复现同一操作；依赖插件的功能在此模式下可能不可用。普通模式重新打开后，逐个检查近期新增或更新的插件。
错误报告主要记录已发生的错误；调试日志则记录一段操作过程，两者不能互相替代。需要过程日志时，在调试模式中使用 帮助 → 调试日志 → 启用，只复现一次问题，再选择 查看输出日志 并关闭记录。发生在启动阶段的问题，可按支持人员指导使用“重启为启用日志模式…”入口。
日志可能包含文献题名、网址、文件路径或请求信息。提交前检查需要提供的范围，问题描述同时写清操作步骤和错误原文；只有日志编号不能说明当时做了什么，也不等于已向支持说明问题。
可按下面的形式反馈：
红豆版本与系统：……；入口：……；操作：打开某条目后点击……；预期：……；实际提示：……；复现范围：全部条目／某一附件／某一来源；开始时间与最近变更：……。
如果旧外部工具或 Connector 提示应用不可用，先确认红豆桌面端正在运行，再打开 设置 → 高级 → Zotero 工具兼容，点击 检查状态；展开 使用说明与诊断，需要反馈时使用 复制诊断信息。端口、进程或链接关联问题处理后，再重新勾选“允许 Zotero 工具连接红豆”。详见兼容设置。本机连接、账号登录与来源网站访问权限是不同问题，不能通过退出账号反复登录来修复端口占用。
