日誌記錄與診斷

上次更新：2026/10/14

QV2QS 每次執行時都會寫入結構化診斷日誌。記錄系統有兩個層級：一個持久的系統日誌，可在多次執行後仍保留；以及一個隨每次執行生成的結構化日誌，會與轉換輸出一起提供。

系統日誌

QV2QS 在磁碟上的固定位置保留一個滾動日誌檔案。系統日誌在可執行檔啟動時開始，並記錄獨立於任何專案或批次的應用程式層級事件。

地點： %LOCALAPPDATA%\QV2QS\qv2qs.log

系統日誌使用具有以下設定的輪替檔案處理器。

當作用中記錄檔達到 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

時間戳記衝突

如果兩個執行在同一秒內啟動並產生相同的時間戳記，QV2QS 會將 _2、_3 或後續數字附加到檔案名稱，以避免覆寫。

要檢查哪個日誌

QV2QS 在執行過程的不同階段，寫入兩個獨立的日誌。系統日誌始終可用。每次執行的日誌只會在啟動初始化完成後建立。

日誌級別

提供五個日誌級別，從最詳細到最不詳細的順序列出。

使用 --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 以擷取詳細的引擎解析步驟，包括在引擎探索期間檢查的檔案路徑。

主控台輸出與檔案記錄

控制台輸出與檔案記錄是獨立的系統。

主控台輸出不會顯示在日誌檔案中。此 --console silent 旗標會抑制主控台輸出，而不影響檔案記錄。

CLI 引數

了解更多

• 引數參考
• 疑難排解