故障排除

如果您在使用 OpenShot 时遇到冻结、崩溃或错误消息等问题，有许多不同的技术可以帮助排查问题。

使用日志排查问题

日志是记录 OpenShot 操作内容的文本文件，同时包含警告和错误信息。这些文件可以帮助支持团队了解问题，即使您没有在屏幕上看到错误消息。

OpenShot 会在您的主文件夹内的 .openshot_qt 文件夹中保存两个日志文件。在 Linux 和 macOS 上，该位置表示为 ~/.openshot_qt/。该文件夹可能在您的文件管理器中被隐藏。

这两个日志文件
文件	记录内容
`openshot-qt.log`	编辑器中的活动：启动 OpenShot、加载项目、更改设置和使用界面。通常这是调查问题时最好的起点。
`libopenshot.log`	OpenShot 视频和音频引擎中的活动，该部分负责读取媒体并构建预览和导出视频中使用的图像和声音。详细的引擎日志有助于调查播放和导出问题。

这些文件记录同一应用程序的不同部分。报告问题时，如果可用，请同时包含这两个文件。您不需要自己理解每一行内容。

选择要记录 OpenShot 的哪一部分

打开 编辑 → 首选项 → 高级 以找到这两个设置：

首选项和对应的终端选项
首选项	对应参数	日志文件
用户界面调试日志	`--debug-ui`	`openshot-qt.log`
视频和音频引擎调试日志	`--debug-engine`	`libopenshot.log`

这两个首选项默认均关闭，保持正常的摘要消息。开启其中一个会立即向其日志文件添加详细信息，但不会更改另一个日志或向终端添加消息。首选项在启动间保持启用状态，直到您关闭它们。

用户界面调试日志 是解决启动、项目加载、设置或界面问题的良好起点。视频和音频引擎调试日志 添加有关视频和音频处理的详细信息，有助于调查播放和导出问题。引擎日志可能迅速增长，且可能导致 OpenShot 变慢。请在重现问题前短暂开启此设置，之后关闭。

引擎首选项以前称为 调试模式（详细）。其保存的开/关设置会继承到新名称。

使用终端启动一次

终端是您输入命令的窗口。对应的参数启用与首选项相同的额外详细信息，并在终端中显示：

openshot-qt --debug-ui

这会记录一次启动的界面详细信息。常用的 --debug 和简写 -d 选项与 --debug-ui 完全相同。要记录视频和音频引擎详细信息，请使用：

openshot-qt --debug-engine

要同时收集这两种详细信息：

openshot-qt --debug-ui --debug-engine

重复导致问题的步骤，然后关闭 OpenShot 并收集日志。这些参数不会更改您保存的首选项。正常启动 OpenShot 会恢复您常用的日志设置。

openshot-qt.log 达到约 25 MB 时会启动新文件，并保留三个旧副本。libopenshot.log 会随着消息添加不断增长。保存所需日志后，您可以在关闭 OpenShot 时删除旧日志文件。

其他命令行选项

大多数用户只需使用上述两个控制。以下选项让您选择写入文件或显示在终端的详细程度。这里，console 指终端输出。

日志选项
选项	功能说明
`--debug-ui`、`--debug` 或 `-d`	启用用户界面调试日志，记录到文件和终端。
`--debug-engine`	启用视频和音频引擎调试日志，记录到文件和终端。
`--debug-file`	向 `openshot-qt.log` 添加编辑器详细信息，但不添加终端详细信息。
`--debug-console`	在终端添加编辑器详细信息，但不添加文件详细信息。
`--log-level LEVEL`	设置两个日志文件及其终端输出的详细级别。
`--log-file-level LEVEL`	设置两个日志文件的详细级别，不影响终端设置。
`--log-console-level LEVEL`	设置终端中编辑器和引擎的详细级别，不影响文件设置。

将 LEVEL 替换为 debug 以获取详细信息，或 info 以获取正常摘要。warning 显示警告和错误；error 显示错误和严重故障；critical 仅显示严重故障。off 停止普通日志消息，但现有的崩溃诊断仍可能被写入。大写名称如 DEBUG 也有效。

例如，要在**两个文件**中收集详细消息，同时保持终端在其通常级别：

openshot-qt --log-file-level debug

这也启用了大型引擎日志，因此请短暂使用。旧的 --debug-file 和 --debug-console 选项仍然有效，尽管它们未在 --help 中列出。

环境变量

环境变量是在程序启动时传递的命名设置。当从脚本启动 OpenShot 或支持人员要求您尝试特定设置时，这些变量非常有用。正常使用时无需设置它们。

可选环境设置
变量	控制内容
`OPENSHOT_LOG_LEVEL`	文件和终端中的详细信息。
`OPENSHOT_LOG_FILE_LEVEL`	仅文件中的详细信息。
`OPENSHOT_LOG_CONSOLE_LEVEL`	仅终端中的详细信息，适用于 OpenShot 的两个部分。
`LIBOPENSHOT_LOG_LEVEL`	视频和音频引擎的详细信息，包含文件和终端。
`LIBOPENSHOT_LOG_FILE_LEVEL`	仅 `libopenshot.log` 中的详细信息。
`LIBOPENSHOT_LOG_CONSOLE_LEVEL`	仅终端中的引擎详细信息。

例如，此 Linux/macOS 终端命令请求在其文件中记录一次启动的详细引擎日志：

LIBOPENSHOT_LOG_FILE_LEVEL=debug openshot-qt

如果设置重叠，命令行选项优先，其次是环境变量，然后是首选项，最后是默认设置。每个控制仅影响其描述的输出：--debug 不会覆盖引擎偏好。临时覆盖不会更改您保存的偏好。将鼠标悬停在任一复选框上以查看是否有其他设置控制该日志文件。

在环境设置中，针对引擎，LIBOPENSHOT_ 值优先于 OPENSHOT_ 值。在任一组中，仅文件或仅终端级别优先于通用级别。命令行选项遵循相同的文件/终端规则。相同输出的冲突命令行级别将被拒绝；无效的环境级别会被报告并忽略。

对于旧脚本，只要存在 LIBOPENSHOT_DEBUG，即使其值为 0，仍会在终端启用详细的引擎消息。较新的级别设置优先于它。LIBOPENSHOT_LOG_FILE 适用于单独使用引擎的程序；OpenShot 本身使用上述日志文件夹。更改日志设置不会更改您的错误报告偏好。

Windows 11 无响应

如果您在 Windows 11 上遇到冻结，这是 PyQt5 与 Windows 11 之间的已知问题，涉及 Qt 的辅助功能。在 OpenShot 中按下 Ctrl+C （仅限 Windows 11 ）会触发此问题。OpenShot 会变得无响应，并且存在内存泄漏（即 OpenShot 无响应时间越长，内存泄漏越严重，直到 OpenShot 最终崩溃或用户终止进程）。

一个简单的解决方法是在 Windows 11 上避免使用 Ctrl+C ，改用右键菜单中的复制/粘贴。另一种方法是将“复制”快捷键从 Ctrl+C 重新映射为其他按键，例如 Alt+C 。您可以在 OpenShot 的首选项中更改键盘映射。参见键盘。

Windows 下使用 GDB 调试

如果您在 Windows 10/11 上使用 OpenShot 时遇到崩溃或冻结，以下逐步说明将帮助您确定崩溃原因。这些说明将显示 OpenShot 源代码中崩溃位置的堆栈跟踪信息。这些信息对我们的开发团队非常有用，也非常适合附加到错误报告中（以加快解决速度）。

安装最新的每日构建版本

在附加调试器之前，请下载 OpenShot 的**最新版本** ：https://www.openshot.org/download#daily。将此版本的 OpenShot 安装到默认位置：C:\Program Files\OpenShot Video Editor\ 。有关在 Windows 上调试 OpenShot 的详细说明，请参见 ` 此维基 <https://github.com/OpenShot/openshot-qt/wiki/Windows-Debugging-with-GDB>`_ 。 this wiki

安装 MSYS2

Windows 版本的 OpenShot 是使用名为 MSYS2 的环境编译的。要将 GDB 调试器附加到我们的可执行文件 openshot-qt.exe ，您必须先安装 MSYS2。此步骤只需执行一次。

下载并安装 MSYS2：http://www.msys2.org/
运行 MSYS2 MinGW x64 命令提示符（例如：C:\msys64\msys2_shell.cmd -mingw64 ）
更新所有软件包（复制/粘贴以下命令 ）：
```
pacman -Syu
```

安装 GDB 调试器（复制/粘贴以下命令 ）：

pacman -S --needed --disable-download-timeout mingw-w64-x86_64-toolchain

使用 GDB 调试器启动 OpenShot

运行 MSYS2 MinGW x64 命令提示符（例如：C:\msys64\msys2_shell.cmd -mingw64 ）

更新 PATH（复制/粘贴以下命令 ）：

export PATH="/c/Program Files/OpenShot Video Editor/lib:$PATH"
export PATH="/c/Program Files/OpenShot Video Editor/lib/PyQt5:$PATH"

将 OpenShot 加载到 GDB 调试器中（复制/粘贴以下命令 ）：

cd "/c/Program Files/OpenShot Video Editor"/
gdb openshot-qt.exe

从 GDB 提示符启动 OpenShot（复制/粘贴以下命令 ）：

run --debug

打印调试信息

一旦 OpenShot 成功启动并附加了 GDB，您只需在 OpenShot 中触发崩溃或冻结。当发生崩溃时，切换回 MSYS2 MinGW64 终端，运行以下命令之一（输入命令后按回车）。通常，第一个输入的命令是 bt ，表示 backtrace 。更多命令列于下方。

(gdb) run            (launch openshot-qt.exe)
(gdb) CTRL + C       (to manually break out   OR   wait for a crash / segmentation fault)
(gdb) bt             (Print stack trace for the current thread #)
(gdb) info threads   (to view all threads, and what they are doing. Look for `__lll_lock_wait` for Mutex/deadlocks)
(gdb) thread 35      (Switch to thread number, for example thread 35)

高DPI / 4K 显示器

OpenShot 视频编辑器对高DPI（每英寸点数）显示器提供强大的支持，确保界面在不同DPI设置的显示器上清晰锐利且易于阅读。这种支持在4K显示器和其他高分辨率显示器上尤为有用。

按显示器的DPI感知

OpenShot 支持按显示器分别感知DPI，这意味着它可以根据每个连接显示器的DPI设置动态调整缩放比例。这有助于在不同显示器之间提供一致的使用体验。

Windows上的DPI缩放

在Windows上，OpenShot会将缩放因子四舍五入到最接近的整数值，以保持视觉完整性。这有助于避免界面中的视觉伪影，并保持界面元素清晰且对齐良好。由于这种四舍五入，某些缩放选项可能导致字体和界面元素比预期更大。

125% 缩放 会四舍五入为 100%
150% 缩放 会四舍五入为 200%

细粒度调整的解决方法

虽然四舍五入有助于保持界面整洁，但对于需要更精确缩放控制的用户，有一些解决方法。由于可能出现视觉伪影，这些方法**不推荐**使用：

QT_SCALE_FACTOR_ROUNDING_POLICY=PassThrough
- 设置此环境变量可以禁用四舍五入，从而实现更精确的缩放。
- 注意： 这可能会导致视觉伪影，尤其是在时间轴中，因此不推荐使用。
QT_SCALE_FACTOR=1.25 （或类似值）
- 手动设置缩放因子可以对字体和界面缩放进行更细致的调整。
- 这也可以通过“首选项”（用户界面缩放）设置，但在Windows上使用小数缩放时可能会出现边框/线条问题。
- 注意： 此方法也可能导致视觉伪影，并使OpenShot更难使用。

有关调整这些环境变量的更多信息，请访问 https://github.com/OpenShot/openshot-qt/wiki/OpenShot-UI-too-large。