转换的工作原理

上次更新日期：2026/10/14

转换管道具有以下阶段：

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

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

转换模式

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

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

仅本地模式

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

用例

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

限制

部署阶段处理一些 qlik app build 无法单独执行的操作。运行仅本地模式，然后手动部署build/文件夹，并使用独立的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 在部署阶段将工作表发布为基础工作表。在共享空间中，其他用户将看不到任何工作表，直到工作表被手动发布。

源文件安全

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

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

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

输出文件夹结构

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

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

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

转换后

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

发布前修复

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

发布前验证

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

波兰语

10. 根据需要在 Qlik Sense 应用程序编辑器中调整字体、颜色或对象位置。有关布局定位的指导，请参阅转换布局设置。

有关报告内容的完整说明，请参阅转化报告。

了解更多

• 快速入门
• 用户界面
• 命令行界面
• 转换布局设置
• 转化结果