# 转换的工作原理

转换管道具有以下阶段：

* 提取 — 如果 `--generatePrj` 已启用，QV2QS 将启动 QlikView Desktop，将 QVW 文件提取到 PRJ 文件夹中。QV2QS 使用捆绑的便携式引擎，除非检测到 QlikView Desktop 的系统安装。有关详细信息，请参阅[QlikView Desktop 引擎](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/getting-started/qlikview-desktop-engine.htm)。
* 解析 — QV2QS 读取 PRJ 文件夹，并解析每个对象定义、工作表布局、加载脚本、变量和文档属性。QV2QS 还会直接读取 QVW/QVF 二进制文件，以提取元数据、变量以及文件中嵌入的任何隐藏加载脚本。
* 转换 — 每个 QlikView 对象都映射到一种 Qlik Sense 可视化类型。维度、度量、表达式、样式和布局位置被转换为 Qlik Sense JSON 格式。
* 写入 — QV2QS 将转换后的应用程序结构作为一组 JSON 文件写入输出文件夹。
* 部署 (仅云模式) — QV2QS 在租户上创建应用程序，上传媒体，构建应用程序，并可选择使用数据重新加载应用程序。
* 报告 — QV2QS 生成一份转换报告，总结了结果、自动化评分以及任何需要手动关注的项目。

部署阶段在构建到 Qlik Cloud 和导出 QVF 模式下运行。在仅本地模式下，QV2QS 将转换后的输出写入磁盘，而无需连接到 Qlik Cloud。报告阶段在所有模式下运行。

## 转换模式

QV2QS 支持三种转换模式。在向导的设置步骤中选择模式，或使用相应的 CLI 标志。

| 模式 | CLI 标志 | Qlik Cloud 必需 | 输出 | 部署阶段 |
| --- | --- | --- | --- | --- |
| 构建到 Qlik Cloud | *(默认)* | 支持 | 应用已部署到租户 | 是 — 创建应用程序、上传媒体、构建、发布工作表 |
| 导出 QVF | `--exportQvf` | 支持 | QVF 文件在磁盘上 | 是 — 在 Qlik Cloud 中构建应用程序，导出为 QVF，然后删除该云应用程序 |
| 仅限本地 | `--unbuildOnly` | 不支持 | 构建文件夹和磁盘上的转换报告 | 不支持 |

构建到 Qlik Cloud 是推荐的迁移模式。导出 QVF 可用于生成可移植文件，以共享或导入到另一个租户。仅本地模式旨在用于评估和审查。有关仅限本地限制的详细信息，请参阅下面的部分。

信息注释

用户界面默认为固定画布模式，重新加载已启用，并且自动二进制已启用。CLI 默认使用动态网格模式，重新加载禁用，以及自动二进制禁用。当从向导切换到命令行界面时，请显式指定这些标志以匹配向导的行为。有关参数和默认值的完整列表，请参阅 [参数参考](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)。

## 仅本地模式

本地模式 (`--unbuildOnly`) 执行解析、转换、写入和报告阶段，无需连接到 Qlik Cloud。不需要租户或 API 密钥。QV2QS 会在磁盘上生成完整的转换报告、执行摘要和构建输出文件夹。

### 用例

* 迁移评估 — 运行仅本地模式以生成转换报告、执行摘要、自动化分数和表达式发现，无需 Qlik Cloud 访问。在设置租户凭据之前，评估整个 QVW 资产的转换质量。
* 部署前审查 — 在提交到云部署之前，检查生成的输出（加载脚本、对象定义、变量、维度）。具有变更控制流程的组织可以将输出作为中间产物进行审查。
* 离线或受限环境 — 当托管 QVW 文件的机器没有出站互联网访问权限时，运行“仅本地”模式以在本地生成转换报告。要部署已转换的应用程序，请将 QVW 文件复制到一台具有 Qlik Cloud 访问权限的机器上，并从连接的机器上以构建到 Qlik Cloud 模式运行 QV2QS。

### 限制

部署阶段处理一些 `qlik app build` 无法单独执行的操作。运行仅本地模式，然后手动部署`build/`文件夹，并使用独立的[qlik-cli](https://qlik.dev/toolkits/qlik-cli/)安装，会导致以下不足。

* 媒体文件未上传。背景图像和按钮图像被提取到 `images/` 文件夹，但不包含在 `build/` 文件夹中。该`qlik app build`命令不处理媒体文件。所有背景图像和按钮图像将从已部署的应用程序中缺失。
* 工作表和对象背景引用未解析。QV2QS 在部署阶段使用云应用程序 ID，将背景图片 URL 注入到工作表和对象 JSON 文件中。本地构建输出不包含背景图片引用。工作表和对象在已部署的应用程序中将没有背景。
* 按钮图片 URL 包含占位符字符串。本地构建输出中的按钮图片使用内部占位符值，而不是已解析的媒体URL。Qlik Sense 引擎无法解析占位符字符串。按钮图片将显示为损坏的。
* 未创建备用状态。备用状态名称写入到 `cloud/alternate_states.json`，在 `build/` 文件夹外部。该 `qlik app build` 命令不处理备用状态。引用非默认状态的对象可能无法正确显示。
* 工作表未发布。该 `qlik app build` 命令创建工作表作为个人对象，仅对应用程序所有者可见。QV2QS 在部署阶段将工作表发布为基础工作表。在共享空间中，其他用户将看不到任何工作表，直到工作表被手动发布。

信息注释

对于完整的部署，包括媒体上传、背景解析、备用状态创建和工作表发布，请使用“构建到 Qlik Cloud 模式”或“导出 QVF 模式”，而不是“仅限本地模式”。

## 源文件安全

QV2QS 不会修改源 QVW 或 QVF 文件的内容。在提取阶段，QV2QS 通过 QlikView Desktop 打开源文档，并保存一个临时副本到系统临时文件夹。QV2QS 随后关闭原始文件，并从临时副本生成 PRJ 文件夹。在 PRJ 生成完成后，QV2QS 会将生成的 `-prj` 文件夹复制回与源文件相同的目录中，并删除临时副本。如果源文件旁边已存在一个 `-prj` 文件夹，QV2QS 会用新生成的版本替换该文件夹。所有其他转换输出将写入到由 `--outputDir` 指定的单独输出目录。

QlikView Desktop 在创建临时副本时，会对源文档获取文件锁。对正在QlikView Desktop中主动打开的或由QlikView Server提供的文件运行QV2QS可能会导致文件锁定冲突或PRJ生成失败。共享网络驱动器上的文件也可能导致相同的冲突。将 `-prj` 文件夹写回网络共享或只读目录也可能失败。

为避免对生产环境造成任何风险，请始终使用源文档的副本进行操作。执行以下操作：

1. 将 QVW 或 QVF 文件复制到运行 QV2QS 的机器上的本地工作文件夹。
2. 将 QV2QS 指向复制的文件，而不是原始文件。
3. 在开始转换之前，请关闭所有正在运行的 QlikView Desktop 实例。QV2QS 需要独占访问 QlikView Desktop。

警告注释

请勿将 QV2QS 直接运行于 QlikView Server 文档文件夹、生产网络共享或在 QlikView Desktop 中打开的文件。始终使用源文档的本地副本。

## 典型时序

QV2QS 专为速度而设计。完整的管道在几分钟内完成，而不是几小时。下表显示了单个应用程序转换的典型持续时间。

| 阶段 | 典型持续时间 | 注释 |
| --- | --- | --- |
| 提取 (PRJ 生成) | 5–15 秒 | 取决于 QVW 复杂性。如果 PRJ 文件夹已存在，则已跳过。 |
| 解析 + 转换 + 写入 | 30 秒以内 | 核心 XML 到 JSON 转换。处理包含数百个对象的复杂应用程序。 |
| 部署 (云构建) | 1–3 分钟 | 包括应用程序创建、媒体上传和在租户上构建应用程序。 |
| 重新加载 | 因情况而异 | 取决于数据量、数据源延迟和租户资源。一个典型的 QVW 的二进制加载不到一分钟即可完成。 |

一次包含云部署和数据重新加载的单应用程序转换，通常在两到五分钟内端到端完成。仅限本地的转换 (`--unbuildOnly`) 可在30秒内完成。

在批处理模式下，QV2QS 会并行转换多个项目。总批处理时间与项目数量除以工人数量的比值成正比。对于 20 个应用程序的批次，配备四名工作器，预计本地转换阶段大约是单个应用程序持续时间的五倍，再加上云部署时间。

## 输出文件夹结构

该 `--outputDir` 参数 指定输出根。QV2QS 会在输出根目录内创建一个子文件夹，该子文件夹的名称与 QVW 文件（或 PRJ 文件夹）的名称相同。项目的所有转换输出都写入该子文件夹中。如果两个 QVW 文件共享相同的名称，QV2QS 会附加 `_2`、`_3` 以及后续数字以避免冲突。此行为与批处理模式匹配，其中每个项目也会获得一个专用子文件夹。

```
<outputDir>/
  <ProjectName>/
    build/
    images/
    reports/
    logs/
    cloud/
    qvf/
```

QV2QS 会创建输出文件夹（如果该文件夹尚不存在）。如果该文件夹是同一 QVW 上次运行中已存在的，QV2QS 会重复使用该文件夹。文件夹中的现有日志文件将保留，除非启用清理日志。输出目录不得与任何源目录相同或为其父目录。QV2QS 在开始转换之前会验证输出路径，如果路径重叠则报告错误。项目子文件夹包含以下内容：

| 文件夹/文件 | 目录 |
| --- | --- |
| `build/` | `qlik app build` 的 Qlik Sense 应用程序结构。包含 `config.yml` (构建清单)、`script.qvs` (加载脚本)、`app-properties.json`、`connections.yml` (数据连接)、`dimensions.json` (主维度)、`measures.json` (主度量)、`variables.json`，以及一个 `objects/` 子文件夹，其中包含每个工作表和可视化一个 JSON 文件。 |
| `images/` | 提取的媒体文件（按内容哈希去重）和 `backgrounds.json` （后台清单）。 |
| `reports/` | `executive_summary.json`、`executive_summary.html`以及 Excel 转换报告（`*_conversion_report_*.xlsx`）（如果已启用）。 |
| `logs/` | 每次运行的结构化日志文件。 |
| `cloud/` | `cloud_state.json` (应用程序 ID、媒体哈希、工作表 ID 映射、时间戳) 和 `alternate_states.json`。在云部署期间创建。 |
| `qvf/` | 导出的 QVF 文件（在`--exportQvf`使用时创建）。 |
| `.qv2qs_source` | 记录了哪个 QVW 生成了子文件夹的标记文件。QV2QS 使用标记来检测名称冲突，并在后续运行中重用正确的文件夹。 |

提示注释

转换完成后，可以直接从向导打开输出文件夹。

## 转换后

转换完成后，请按优先级分组处理以下项目。

发布前修复

1. 打开位于`reports/`子文件夹中的Excel转换报告，并查看Follow-up\_Objects工作表。修复所有标记为错误的项（未能转换的对象），然后是占位符（需要重建的对象），然后是需要调整（部分转换的对象）。
2. 在分析工作表上查看分析结果，包括宏引用、区域权限使用情况以及可能需要手动处理的加载脚本模式。
3. 验证表达式是否正确求值。QV2QS 自动修复转换过程中的集合分析引用问题。审查计算维度、条件着色和使用QlikView专用函数（`GetCurrentField()`、`MsgBox()`）的表达式，这些函数需要手动重写。
4. 检查 Overflow\_Actions 工作表，以查找其中多余的维度或度量已移至备选集合的对象。

发布前验证

1. 在 Qlik Sense 中打开转换后的应用程序，并验证工作表布局、对象位置和背景图像是否按预期显示。
2. 确认选项卡容器导航（按钮条或选项卡式容器）在内容区域之间正确切换。
3. 测试向下钻取和循环组的循环行为，在使用了维度组的图表上。
4. 验证显示条件是否按预期隐藏和显示对象。
5. 检查列表框和表格中的排序顺序，尤其是对于日期类字段。

波兰语

1. 根据需要在 Qlik Sense 应用程序编辑器中调整字体、颜色或对象位置。有关布局定位的指导，请参阅[转换布局设置](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)。

有关报告内容的完整说明，请参阅[转化报告](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-results/conversion-report.htm)。

## 了解更多

* [快速入门](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/getting-started/quick-start.htm)
* [用户界面](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/user-interface/index.htm)
* [命令行界面](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/command-line-interface/index.htm)
* [转换布局设置](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)
* [转化结果](https://help.qlik.com/zh-CN/migration/Content/Qv2qsMigration/conversion-results/conversion-outcomes.htm)