# 参数参考

下表列出了按类别分组的所有可用参数。

信息注释

用户界面对某些设置应用了不同的默认值。向导默认为固定画布模式、重新加载已启用和自动二进制已启用。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-CN/migration/Content/Qv2qsMigration/getting-started/how-conversion-works.htm#local-only-mode)。 | 关 |
| `--qsAppName NAME` | Qlik Cloud 中 Qlik Sense 应用程序的名称 | 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-CN/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-CN/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`）。所有标记都已小写。如果任何令牌等于以下任一值，则字段匹配：`date`, `dates`, `month`, `months`, `year`, `years`, `quarter`, `quarters`, `qtr`, `qtrs`, `week`, `weeks`, `day`, `days`, `fiscal`, `fy`, `period`, `calendar`。字段也匹配，如果任何令牌以`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` 显式禁用它。

这两个修复都仅适用于维度和度量表达式。不支持的功能发现不予修改。当修复被禁用时，已标记的模式将保留在表达式发现工作表中以供手动审查。

## 了解更多

* [常见工作流程](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/command-line-interface/common-workflows.htm)
* [日志记录和诊断](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/command-line-interface/logging-and-diagnostics.htm)
* [布局模式](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)