日志记录和诊断
上次更新日期：2026/10/14QV2QS 在每次运行期间写入结构化诊断日志。日志系统分为两层：一个跨运行持久的系统日志，以及一个随转换输出一同交付的每次运行结构化日志。
系统日志
QV2QS 在磁盘上的一个固定位置维护一个滚动日志文件。系统日志在可执行文件启动时启动，并记录独立于任何项目或批次的应用程序级事件。
位置: %LOCALAPPDATA%\QV2QS\qv2qs.log
系统日志使用循环文件处理程序，并采用以下设置。
| 设置 | 值 |
|---|---|
| 最大文件大小 | 25 MB |
| 保留的备份文件 | 3 |
| 文件模式 | qv2qs.log, qv2qs.log.1, qv2qs.log.2, qv2qs.log.3 |
当激活日志文件达到 25 MB 时，QV2QS 会轮换该文件并创建一个新的日志文件。保留最近的三份备份。较旧的备份会被自动删除。
每次运行的结构化日志
每次转换运行都会生成一个单独的日志文件，其中包含该次运行的详细事件。文件名为 qv2qs_run_<version>_<timestamp>.log，采用制表符分隔值 (TSV) 格式，并包含一个 JSON 数据列。
默认位置: %LOCALAPPDATA%\QV2QS\logs\
在单项目模式下，QV2QS 会在输出文件夹初始化后，将日志文件提升到项目输出文件夹的 logs/ 子文件夹中（例如，<outputDir>/Sales/logs/）。日志文件包含在转换输出中。
在批处理模式下，每个项目的日志会写入到每个项目输出文件夹中的 logs/ 子文件夹。
日志文件格式
每个日志文件都以一个 TSV 标题行开头：
ts_utc level version run_id logger event message data
| 列 | 描述 |
|---|---|
ts_utc
|
ISO 8601 UTC 毫秒级精确度时间戳 |
level
|
日志级别：DEBUG、INFO、WARNING、ERROR 或 CRITICAL |
version
|
QV2QS 版本 |
run_id
|
格式为唯一的运行标识符 YYYYMMDD-HHMMSS-<hex> |
logger
|
记录器名称 (通常为qv2qs) |
event
|
事件类型字符串 (例如，startup、conversion_complete、batch_local_complete) |
message
|
人类可读的描述 |
data
|
包含上下文相关的键值对的 JSON 对象 |
时间戳冲突
如果两次运行在同一秒内开始并生成相同的时间戳，QV2QS 会在文件名后附加 _2、_3 或后续数字，以避免覆盖文件。
查看哪个日志
QV2QS 在运行的不同阶段写入两个独立的日志。系统日志始终可用。每次运行的日志仅在启动初始化完成后创建。
| 场景 | 首先检查日志 | 原因又是？ |
|---|---|---|
| 进程崩溃或立即退出 | 系统日志 | 每次运行的日志尚未创建 |
| PRJ 生成在转换启动前失败 | 系统日志 | PRJ 事件在输出目录初始化之前被记录 |
| 批处理运行显示失败文件，没有详细信息 | 系统日志 | 批处理级别错误（缺少 QlikView Desktop，先决条件失败）会记录在系统日志中 |
| 转换产生意外输出 | 单次运行日志位于输出目录中 | 对象级转换决策和警告会记录在每次运行的日志中 |
| 云部署失败 | 单次运行日志位于输出目录中 | API 调用、身份验证错误和上传进度会记录在每次运行的日志中 |
系统日志和每次运行日志在两者都激活的重叠期间记录相同的事件。系统日志在进程启动时开始。单次运行日志在命令行参数解析完毕并创建输出目录后开始。如果在生成单次运行日志之前发生故障，则只有系统日志包含诊断信息。
日志级别
提供五个日志级别，按从最详细到最不详细的顺序列出。
| 级别 | 描述 |
|---|---|
DEBUG
|
详细诊断信息用于故障排除 |
INFO
|
通用操作消息（默认） |
WARNING
|
不会阻止转换的意外情况 |
ERROR
|
影响单个对象或操作的故障 |
CRITICAL
|
中断执行的严重故障 |
使用 --logLevel 或 QV2QS_LOG_LEVEL 环境变量设置日志级别。当两者都设置时，CLI 标志优先。
设置 --logLevel DEBUG 以捕获最详细的输出。调试级别条目包括转换决策、云 API 调用、脚本修改以及对象处理详情。
若要在不修改命令行的情况下启用调试日志记录，请设置环境变量，再运行 QV2QS：
set QV2QS_LOG_LEVEL=DEBUG
QV2QS.exe --prjPath ./MyApp-prj --outputDir ./output --qvw MyApp.qvw --unbuildOnly
日志清理
日志文件在持久性日志目录中跨运行累积。使用 --cleanLogs 在运行开始时删除超过30天的日志文件。清理仅适用于持久性日志目录；输出目录中每个项目的日志不受影响。
秘密遮罩
日志条目自动屏蔽敏感值。API 密钥、令牌、密码和客户端密钥已进行编辑，仅显示最后四个字符。包含敏感信息的命令行参数在记录日志时也会被屏蔽。
QlikView 桌面引擎日志记录
当 PRJ 生成启用时，QV2QS 会记录使用了哪个 QlikView Desktop 引擎来处理每个文件。日志事件 prj_generate_start 记录了捆绑的便携式引擎还是系统安装的版本处于激活状态，并在可用时包含捆绑的可执行文件的文件版本。
与 QlikView Desktop 的连接建立后，prj_qv_ready 事件会记录由正在运行的引擎报告的 QlikView 版本（例如，12.100.20100.0）。当使用捆绑引擎时，exe_file_version 字段记录从可执行文件读取的文件版本。
在批处理模式下，日志事件 prj_batch_prereq 会在处理任何文件之前，记录整个批处理的引擎选择和捆绑版本。如果捆绑引擎或系统安装均不可用，错误将记录为prj_batch_no_qv在系统日志中。
设置 --logLevel DEBUG 以捕获详细的引擎解析步骤，包括在引擎发现期间检查的文件路径。
控制台输出与文件日志记录
控制台输出和文件日志是独立的系统。
| 方面 | 控制台 | 文件日志 |
|---|---|---|
| 格式 | 格式化文本，带有可选颜色和微调器 | 结构化的 TSV 包含 JSON 数据 |
| 由...控制 | --console pretty\|plain\|silent\|ui
|
--logLevel, --logDir |
| 内容 | 面向用户的进度和结果 | 完成诊断事件 |
| 秘密屏蔽 | 不适用 | 自动应用 |
控制台输出不会出现在日志文件中。该 --console silent 标志抑制控制台输出，而不影响文件日志记录。
CLI 参数
| 参数 | 描述 | 默认 |
|---|---|---|
--logLevel LEVEL
|
日志详细程度：DEBUG, INFO, WARNING, ERROR, CRITICAL |
INFO
|
--logDir FOLDER
|
覆盖每次运行的日志输出文件夹。相对路径从当前工作目录解析，而不是从输出目录解析。不影响 %LOCALAPPDATA% 处的持久系统日志。 |
%LOCALAPPDATA%\QV2QS\logs\ (单项目) 或 <outputDir>/logs/ (批量) |
--cleanLogs
|
运行前删除超过30天的日志文件 | 关 |