# 引數參考

下表列出所有可用的引數，並依類別分組。

資訊備註

使用者介面會對某些設定套用不同的預設值。精靈預設為固定畫布模式、重新載入已啟用，且自動二進位已啟用。CLI 預設為動態格線模式、重新載入已停用，且自動二進位已停用。從精靈模式切換至 CLI 時，請明確指定這些旗標以符合精靈的行為。

## 輸入與輸出

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--prjPath PATH` | QV PRJ 資料夾或 ZIP 檔案的路徑。也接受 PRJ zip 壓縮檔。 | — |
| `--qvw PATH` | QVW 或 QVF 檔案的路徑。在單一專案模式中為必填項。 | — |
| `--generatePrj` | 在轉換之前，從 QVW 檔案自動產生 PRJ 資料夾 | 關閉 |
| `--outputDir FOLDER` | 輸出根目錄。QV2QS 會自動建立一個以專案名稱命名的子資料夾。必填。 | — |

## 批次模式

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--batchDir FOLDER` | 遞迴掃描一或多個資料夾，以尋找 QVW 和 PRJ 配對。使用 `;` 分隔多個資料夾。 | — |
| `--batchWorkers N` | 最大並行轉換 (`0` = 自動：CPU 核心數減 1) | `0` |
| `--batchFlatOutput` | 將所有輸出直接寫入 `--outputDir` 而不是保留來源資料夾階層 | 關閉 |

## Qlik Cloud

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--unbuildOnly` | 僅限本機模式。生成建置輸出和轉換報告至磁碟，無需連線至 Qlik Cloud。適用於評估、檢閱及離線使用。本地輸出不包含媒體上傳、背景解析、替代狀態建立或工作表發佈。如需詳細資訊，請參閱[轉換運作方式](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/getting-started/how-conversion-works.htm#local-only-mode)。 | 關閉 |
| `--qsAppName NAME` | Qlik Sense 應用程式在 Qlik Cloud 中的名稱 | QVW 檔案名稱、PRJ 資料夾名稱，或輸出資料夾名稱 |
| `--appId APP_ID` | 更新現有的 Qlik Cloud 應用程式，而非建立新的 | — |
| `--appIdFile PATH` | 從檔案載入應用程式 ID | — |
| `--reuseAppId` | 如果檔案存在，請重複使用 `cloud/cloud_state.json` 的應用程式 ID | 關閉 |
| `--preserveTargetAppScript` | 保留現有的載入指令碼在目標應用程式中。已轉換的載入指令碼未套用。需要 `--appId` 或 `--reuseAppId`。可與 `--reload` 結合，以執行現有的指令碼。 | 關閉 |
| `--preserveTargetAppVariables` | 保留目標應用程式中的現有變數。轉換後的變數未套用。需要 `--appId` 或 `--reuseAppId`。 | 關閉 |
| `--noBackup` | 重複使用現有應用程式時，跳過自動部署前備份。依預設，QV2QS 會將不含資料的 QVF 匯出至 `cloud/backups/` 再修改應用程式。 | 關閉 |
| `--reload` | 建置後重新載入應用程式以執行載入指令碼 | 關閉 |
| `--autoBinary` | 上傳 QVW/QVF 到 Qlik Cloud 以進行二進位載入，然後在重新載入後刪除。需要 `--reload`。在單一專案模式下，也需要 `--qvw`。在批次模式下，QVW 檔案會自動探索。與 `--binaryAppId` 互斥。 | 關閉 |
| `--binaryAppId APP_ID` | 使用 Qlik Cloud 中現有的應用程式進行二進位載入，而非上傳。與 `--autoBinary` 互斥。 | — |
| `--noPublishSheets` | 建置後請勿發佈工作表。依預設，QV2QS 會將所有轉換的工作表發佈為基礎工作表，以便每個應用程式使用者都能看到它們。使用此旗標以將工作表保留為個人（未發佈）物件。當重複使用現有的應用程式時 (`--reuseAppId` 或 `--appId`)，先前發佈的工作表會自動還原；此旗標僅適用於目前轉換中新增的工作表。 | 關閉 |
| `--noData` | 建置後無資料 | 關閉 |
| `--exportQvf` | 匯出應用程式為 QVF 檔案，然後刪除雲端應用程式 | 關閉 |
| `--exportQvfNoData` | 匯出 QVF 時不含資料。需要 `--exportQvf`。 | 關閉 |
| `--mediaUploadWorkers N` | 平行媒體上傳執行緒 | `2` |
| `--buildConfig PATH` | 建置組態資訊清單已傳遞至 `qlik app build`。QV2QS 會在轉換期間自動產生此檔案。僅在提供自訂資訊清單時才覆寫。 | `config.yml` |
| `--spaceId SPACE_ID` | 用於應用程式建立的目標 Qlik Cloud 空間 | 個人空間 |

## 驗證

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--qlikContext NAME` | qlik-cli 上下文名稱用於驗證 | — |
| `--qlikTenantUrl URL` | 租戶 URL (`https://<tenant>.<region>.qlikcloud.com`)。當與 `--qlikApiKey` 結合時，可直接進行驗證，而無需建立 qlik-cli 內容。 | — |
| `--qlikApiKey KEY` | 用於驗證的 API 金鑰。當與 `--qlikTenantUrl` 結合時，無需建立 qlik-cli 上下文即可直接驗證。金鑰未寫入磁碟。 | — |
| `--qlikCliPath PATH` | qlik-cli 可執行檔的路徑 | 捆綁 |
| `--qlikContextsFile PATH` | 覆寫 qlik-cli 內容檔案位置 | — |
| `--qlikNoPrompt` | 如果缺少驗證，立即失敗並以結束代碼 1 結束。無互動提示。適用於 CI/CD 管線。 | 關閉 |
| `--setupQlikAuth` | 配置 Qlik Cloud 驗證並退出。當同時提供 `--qlikTenantUrl` 和 `--qlikApiKey` 時，則不需要。 | — |

## 版面配置與樣式

關於固定畫布和動態格線模式的詳細說明，請參閱[轉換版面配置設定](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)。

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--fixedSheetCanvas` | 啟用固定大小的像素畫布工作表 (QlikView 樣式定位) | 關閉 |
| `--fixedSheetCanvasScale FACTOR` | 依此係數縮放畫布尺寸 | `1.4` |
| `--fixedSheetCanvasObjectScale FACTOR` | 按此係數縮放物件位置和大小 | `1.4` |
| `--fixedSheetCanvasMinWidthPx PX` | 最小畫布寬度 (單位：像素) | `1200` |
| `--fixedSheetCanvasMinHeightPx PX` | 最小畫布高度 (單位：像素) | `700` |
| `--perSheetCanvasSize` | 使用每個工作表的畫布尺寸而非統一大小 | 關閉 |
| `--noAutoExtendDynamicSheet` | 停用動態模式中自動延伸工作表高度 | 關閉 |
| `--layoutShrinkX STEPS` | 縮小版面配置容器寬度，依 N 格線步驟 (0–23) | `0` |
| `--layoutShrinkY STEPS` | 縮小版面配置容器高度 N 格線步長 (0–11) | `0` |
| `--cropCanvasWidth PX` | 將畫布裁切為精確的像素寬度。僅限固定畫布模式。必須與 `--cropCanvasHeight` 一起指定。與 `--perSheetCanvasSize` 互斥。 | `0` |
| `--cropCanvasHeight PX` | 將畫布裁切為精確的像素高度。僅限固定畫布模式。必須與 `--cropCanvasWidth` 一起指定。與 `--perSheetCanvasSize` 互斥。 | `0` |
| `--maxCanvasWidth PX` | 畫布最大寬度（像素）。`0` 停用此限制。僅限固定畫布模式。 | `0` |
| `--maxCanvasHeight PX` | 畫布最大高度（像素）。`0` 停用此限制。僅限固定畫布模式。 | `0` |
| `--appTheme THEME` | Qlik Sense 應用程式佈景主題套用至轉換後的應用程式。接受任何內建的佈景主題識別碼 (`sense`、`horizon`、`breeze`、`card`) 或安裝在租用戶上的自訂佈景主題名稱。Sense Classic (`sense`) 是最不干擾的佈景主題，並與 QlikView 產生最高的 1:1 擬真度。非經典佈景主題可能會變更物件邊框、背景顏色、字型和內距。佈景主題僅設定預設值；使用者可以隨時在 Qlik Sense 用戶端中切換佈景主題。 | `sense` |
| `--disableSheetBackgrounds` | 跳過工作表背景圖片擷取 | 關閉 |
| `--noDocBgFallback` | 請勿將文件背景套用至沒有背景的工作表 | 關閉 |
| `--sheetBackgroundColor COLOR` | 純色填滿所有工作表 (`#RRGGBB`、`#RRGGBB@0.5` 或 `transparent`) | — |
| `--showSheetHeader` | 顯示工作表標頭區域 | 關閉 |
| `--skipHiddenSheets` | 省略顯示條件恆為假的工作表 | 關閉 |

## 轉換報告

主控台報告和 Excel 報告在 CLI 模式和使用者介面中預設皆已啟用。

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--report` | 啟用主控台轉換報告 | 開啟 |
| `--noReport` | 停用主控台轉換報告 | — |
| `--reportXlsx [PATH]` | 將報表匯出為 Excel 檔案。接受檔案名稱 (例如`MyReport`) 或完整路徑；`.xlsx` 會自動新增。相對名稱會放在 `outputDir/reports/` 中。省略路徑以自動命名。 | 自動 |
| `--noReportXlsx` | 停用 Excel 匯出 | — |
| `--reportIncludeBuiltIns` | 將目前選取項目和搜尋物件納入報表 | 關閉 |

## 主控台與記錄

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--console {pretty,plain,silent,ui}` | 主控台輸出模式 | `pretty` |
| `--dark` | 深色主控台佈景主題 | 開啟 |
| `--light` | 淺色主控台佈景主題 | 關閉 |
| `--surface` | 啟用主控台的背景填滿 | 開啟 (以美觀模式) |
| `--noSurface` | 停用背景填滿 | — |
| `--plain` | `--console plain` 的快速鍵 | — |
| `--silent` | `--console silent` 的快速鍵 | — |
| `--logLevel LEVEL` | 日誌詳細程度： `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | `INFO` |
| `--logDir FOLDER` | 覆寫日誌輸出資料夾 | `%LOCALAPPDATA%\QV2QS\logs\` (單一專案) 或 `<outputDir>/logs/` (批次) |
| `--cleanLogs` | 執行前刪除超過 30 天的記錄檔 | 關閉 |

QV2QS 支援四種主控台輸出模式。

* 美觀 — 格式豐富的輸出，具備色彩、動畫旋轉器、進度條和主題面板。美觀模式是互動式終端機使用的預設值。需要支援彩色的終端機 (Windows 10 以上、PowerShell 5 以上，或類 Unix 的 Shell)。
* 純文字 — 附帶時間戳記的文字輸出，不含 ANSI 跳脫碼。每一行都以耗時戳記和階段標籤為前綴，其格式為 `[MM:SS] [phase] message`。標頭和表格使用 ASCII 字元。適用於 CI/CD 管線、日誌檔案以及不支援 ANSI 格式的終端機。
* 靜默 — 抑制所有標準輸出。僅顯示錯誤。適用於自動化批次處理和不需要主控台輸出的指令碼工作流程。
* UI — 逐行輸出，不含時間戳記或 ANSI 碼。使用者介面會在啟動轉換子程序時自動設定此模式。此格式已針對內嵌記錄檢視器進行最佳化。從終端機執行 `--console ui` 會產生可讀但未經格式化的輸出；若要直接在終端機中使用，請改用 `--plain` 或 `--console pretty`。

`--dark` 和 `--light` 旗標選擇一個顏色佈景主題。深色佈景主題 (預設) 使用深海軍藍 Qlik 風格的調色盤。淺色佈景主題使用淺灰色調色盤。`--surface` 旗標會為每個輸出行啟用一個細微的背景填充。在美觀模式下，表面填充預設為啟用。使用 `--noSurface` 以停用背景填色。

在單一專案模式下，日誌檔案依預設會寫入至 `%LOCALAPPDATA%\QV2QS\logs\`。在批次模式下，日誌檔案會寫入到輸出目錄中的 `logs/` 子資料夾。覆寫位置為 `--logDir`。設定 `--logLevel DEBUG` 以擷取詳細診斷輸出，用於疑難排解轉換問題。在每次執行前，使用 `--cleanLogs` 刪除逾 30 天的日誌檔案。如需日誌檔案位置、輪替和格式的完整說明，請參閱[日誌記錄與診斷](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/command-line-interface/logging-and-diagnostics.htm)。

## 載入指令碼

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--scriptReplacements PATH` | 具有指令碼取代規則的 JSON 檔案。如果提供，則只會執行檔案中的規則。內建預設值不會自動載入。請參閱以下格式。 | — |
| `--noScriptReplacements` | 停用所有指令碼取代。沒有任何規則執行，無論是否提供檔案。 | 關閉 |

依預設，QV2QS 會套用八個內建規則，可將 Windows 反斜線路徑標準化為正斜線，以符合 Qlik Cloud 相容性。下表列出每個內建規則。

| ID | 描述 | 目標： |
| --- | --- | --- |
| 1 | 標準化 `lib://` 路徑中的反斜線 | `lib://DataFiles\subfolder\file.qvd` |
| 2 | 標準化 `STORE...INTO` 路徑中的反斜線 | `STORE table INTO 'C:\data\file.qvd'` |
| 3 | 規範化 `FROM` 路徑 (引號內) 中的反斜線 | `FROM 'C:\data\file.qvd'` |
| 4 | 正規化 `LET` 陳述式路徑中的反斜線 | `LET vPath = 'C:\data\files';` |
| 5 | 正規化 `SET` 陳述式路徑中的反斜線 | `SET vPath = 'C:\data\files';` |
| 6 | 正規化 `BINARY` 陳述式路徑中的反斜線 | `BINARY 'C:\apps\source.qvw'` |
| 7 | 正規化 `FROM` 路徑中的反斜線 (未加引號) | `FROM C:\data\file.qvd` |
| 8 | 在 `$(Variable=path)` 展開中正規化反斜線 | `$(Must_Includes=C:\lib\file.qvs)` |

每條規則都使用兩階段比對程序。「`pattern`」欄位是一個正規表示式，用於選取載入指令碼的區域。該 `search` 欄位接著只會套用在每個符合的區域內。這種方法可避免在目標情境之外發生非預期的替換。

此 `--scriptReplacements` 引數接受一個 JSON 檔案，該檔案將成為所有替換規則的唯一真實來源。當提供檔案時，內建預設值不會自動載入。若要將內建規則與自訂規則一併納入，請從精靈匯出完整的規則集並編輯匯出的檔案。規則以 `execution_order` 順序執行。

提供三種 CLI 行為：

* 沒有旗標 — 八個內建規則執行。
* `--scriptReplacements <file>` — 檔案中的規則才會執行。內建預設值不會自動載入。
* `--noScriptReplacements` — 沒有規則執行。

提示備註

若要建立自訂規則檔案，請開啟精靈，按一下匯出，在指令碼取代區段中，並使用匯出的 JSON 作為起點。匯出的檔案包含所有八個內建規則，格式正確。視需要新增、移除或修改規則，然後使用 `--scriptReplacements` 傳遞檔案。

此 `--scriptReplacements` 檔案是一個規則物件的 JSON 陣列：

```
[
  {
    "description": "Replace server path with lib connection",
    "pattern": "FROM\\s+'[^']*'",
    "search": "\\\\\\\\server\\\\share\\\\",
    "replace": "lib://DataFiles/",
    "is_regex": true,
    "case_sensitive": false,
    "enabled": true,
    "execution_order": 1
  }
]
```

每個規則都有以下欄位：

| 欄位 | 描述 | 必填 |
| --- | --- | --- |
| `description` | 規則的人類可讀標籤 | 是 |
| `pattern` | 選取指令碼區域以供檢查的規則運算式 | 是 |
| `search` | 要在每個符合區域中尋找的文字或正規表達式 | 是 |
| `replace` | 替換文字 | 否 (預設值：空字串，這會刪除符合的文字) |
| `is_regex` | 無論 `search` 是正規表達式 (`true`) 還是字面字串 (`false`) | 否 (預設值: `true`) |
| `case_sensitive` | 比對是否區分大小寫 | 否 (預設值: `false`) |
| `enabled` | 規則是否作用中 | 否 (預設值: `true`) |
| `id` | 用於 UI 追蹤的數值識別碼 | 否 |
| `execution_order` | 控制執行順序的數值。較小的值優先執行。 | 否 (預設值: `0`) |

資訊備註

該檔案也接受 camelCase 欄位名稱 (`isRegex`、`caseSensitive`、`executionOrder`)，以便與從精靈匯出的檔案相容。

## 其他

| 引數 | 描述 | 預設值 |
| --- | --- | --- |
| `--listboxBackgroundExpr EXPR` | 清單方塊背景顏色。`dynamic` 保留 QV 顏色。也接受 `#RRGGBB`、`#AARRGGBB`、`rgb(r,g,b)` 或 `argb(a,r,g,b)`。 | `dynamic` |
| `--disableDateStateStickySort` | 停用日期欄位排序防護。請參閱下方的。 | 關閉 |
| `--fixSingleQuotedSearch` / `--noFixSingleQuotedSearch` | 將集合分析中的單引號萬用字元和比較轉換為雙引號。請參閱下方的。 | 開啟 |
| `--fixUnquotedSetValues` / `--noFixUnquotedSetValues` | 實驗性。在集合分析中，將未加引號的裸字串值用單引號括起來。請參閱下方的。 | 關閉 |
| `--ui` | 啟動使用者介面而非執行轉換 | 關閉 |
| `--port PORT` | 使用者介面埠 | 自動 |
| `--noBrowser` | 啟動 UI 時請勿自動開啟瀏覽器 | 關閉 |
| `--version` | 顯示版本並結束 | — |
| `--accept-eula` | 接受終端使用者授權合約，不顯示互動式提示。適用於 CI/CD 管線與自動化工作流程。 | 關閉 |

### 日期欄位排序防護

依預設，Qlik Sense 會將選取的值排序到清單方塊的頂端。對於日期類型的欄位，例如季度、月份或年份，這種重新排序打破了預期的時間順序。QV2QS 會套用啟發式方法來偵測日期類型的欄位名稱，並抑制這些欄位上的狀態式排序，讓值保持其自然順序，無論選取狀態為何。

該啟發式方法會透過分割非英數字元和駝峰式大小寫邊界來標記化每個欄位名稱 (例如，`OrderDate` 會變成 `order` 和 `date`)。所有權杖皆為小寫。欄位符合，如果任何 Token 等於下列其中一個：`date`、`dates`、`month`、`months`、`year`、`years`、`quarter`、`quarters`、`qtr`、`qtrs`、`week`、`weeks`、`day`、`days`、`fiscal`、`fy`、`period`、`calendar`。如果任何 Token 結尾為 `date`、`month` 或 `year`，該欄位也會符合 (例如 `OrderDate`、`FiscalMonth`)。權杖`update`、`candidate`及`validate`已排除，以避免誤判。比對不區分大小寫，且僅使用英文詞元。非英文欄位名稱（例如，`Monat` 或 `Fecha`）無法偵測。

符合啟發式規則的欄位已移除基於狀態的排序，並停用自動排序。

使用 `--disableDateStateStickySort` 關閉此啟發式。停用時，所有清單方塊欄位會使用預設的 Qlik Sense 排序行為，包括根據狀態的重新排序。

### 集合分析引號修正

QlikView 和 Qlik Sense 對於集合分析修飾符中的引號有不同的解讀方式。QV2QS 在轉換期間應用兩項獨立的修正。單引號搜尋修正預設為啟用。未加引號的設定值修復為實驗性，且預設為停用。

修復單引號搜尋值 (`--fixSingleQuotedSearch`)

包含搜尋語法的單引號值會轉換為雙引號。偵測到的搜尋模式包括萬用字元 (`*`, `?`, `^`)、比較運算子 (`>`, `>=`, `<`, `<=`)、模糊搜尋 (`~`)、運算式搜尋 (`=`)、搜尋修飾詞 (`+`, `-`) 以及複合搜尋 (`(…|…)`, `(…&…)`)：

* `{<Year={'2*'}>}` 變成 `{<Year={"2*"}>}`
* `{<Amount={'>100'}>}` 變成 `{<Amount={">100"}>}`
* `{<Customer={'~company'}>}` 變成 `{<Customer={"~company"}>}`

單引號純文字常值（例如 `'USA'`）以及數值欄位上的單引號值不受影響。使用 `--noFixSingleQuotedSearch` 來停用此修正。

修復未加上引號的設定值 (`--fixUnquotedSetValues`) — *實驗性*

未加引號的純字串值會以單引號括起來：

* `{<Country={USA}>}` 變成 `{<Country={'USA'}>}`

數值 (`2024`)、美元符號變數 (`$(vYear)`) 以及雙引號字串均維持不變。依照預設，此修正為停用。傳入 `--fixUnquotedSetValues` 以將其啟用。使用 `--noFixUnquotedSetValues` 來明確停用它。

這兩項修正僅適用於維度與量值運算式。不支援的函式發現項目不會被修改。當停用修復時，標記的模式會保留在 Expression\_Findings 工作表中以供手動檢閱。

## 瞭解更多

* [常見工作流程](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/command-line-interface/common-workflows.htm)
* [記錄與診斷](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/command-line-interface/logging-and-diagnostics.htm)
* [版面配置模式](https://help.qlik.com/zh-TW/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)