重用现有应用程序
上次更新日期：2026/10/14QV2QS 可以针对现有的 Qlik Sense 应用程序，而不是在每次部署时创建新的应用程序，从而实现迭代开发并保留应用程序 ID。
默认情况下，QV2QS 会在每次部署时创建一个新的应用程序。改为以现有应用程序为目标，以便就地更新应用程序并保留应用程序 ID。这种方法支持迭代开发，并保留引用特定应用程序 ID 的书签和链接。
支持复用的三个论据：
--appId APP_ID— 直接指定应用程序 ID。--appIdFile PATH— 从文本文件的第一行读取应用程序 ID。--reuseAppId— 从项目子文件夹中的cloud/cloud_state.json读取应用程序 ID。此文件会在每次部署后自动写入。
cloud/cloud_state.json 文件存储在项目子文件夹中（例如，<outputDir>/Sales/cloud/cloud_state.json）。该文件记录了应用程序 ID、媒体哈希、工作表 ID 映射、源文件路径以及时间戳。--reuseAppId 标志会自动读取此文件，因此后续运行会更新同一个应用程序，而无需手动输入应用程序 ID。在批处理模式下，--reuseAppId 按项目运行——每个项目都会从其自身的输出子文件夹中读取 cloud_state.json。
工作表 ID 映射
每个 QlikView 文档都通过内部名称（例如 Document\SH01、Document\SH02 等）来标识工作表。Qlik Sense 使用 UUID 来标识工作表。当 QV2QS 首次部署应用程序时，每个转换后的工作表都会获得一个新的 UUID。QV2QS 将 QlikView 工作表名称与 Qlik Sense UUID 之间的映射存储在目标应用程序中，以便在跨部署时保留该关系。
在后续部署到同一应用程序时，QV2QS 会读取存储的映射，并将原始 Qlik Sense UUID 分配给相应的已转换工作表。该映射可防止复制工作表出现在应用程序中，并保留引用特定工作表 ID 的书签、收藏夹和直接链接。
该映射存储在两个位置：
- 在 Qlik Cloud 应用程序内部 — 应用程序内的专用对象保存该映射。如果将应用程序移动到不同空间或导出为 QVF，映射会随应用程序一同移动。
- 在本地项目文件夹中 —
cloud/cloud_state.json文件包含相同映射的副本。--reuseAppId标志从此文件读取应用程序 ID 和映射。
在准备重新部署时，QV2QS 始终从云应用程序（而非本地文件）读取映射。本地文件便于 --reuseAppId 标志定位应用程序 ID。
媒体哈希优化
QV2QS 会计算所有媒体文件（工作表背景、对象背景、按钮图像）的哈希值，并将该哈希值与工作表映射一起存储。在后续部署中，QV2QS 会将当前哈希与存储的值进行比较。如果媒体未更改，则完全跳过上传步骤。
Mapping 验证
在准备替换工作表之前，QV2QS 会对照实时应用程序验证存储的映射。如果在各次部署之间从 Qlik Cloud 应用程序中手动删除了工作表，QV2QS 会检测到该工作表已不存在，从映射中移除陈旧条目，并在下次构建时将相应的 QlikView 工作表视为新工作表。构建完成后，更新后的映射将写回应用程序。
QlikView 源中添加或删除的工作表
在初始部署后向 QlikView 源中添加工作表时，QV2QS 会为该工作表分配一个新的 UUID，并将该条目添加到映射中。当从 QlikView 源中删除工作表时，该工作表将不再出现在构建输出中，并会在构建过程中从 Qlik Cloud 应用程序中删除。已移除工作表的映射条目不会被沿用。
项目文件夹匹配
首次转换后，QV2QS 会向每个项目输出文件夹写入一个 .qv2qs_source 标记文件。该标记记录源 QVW 文件的完整路径。在后续运行中，QV2QS 使用该标记来定位给定 QVW 文件的正确项目文件夹，即使多个文件夹具有相同的基本名称（例如 Sales/、Sales_2/、Sales_3/）。
该标记确保每个 QVW 文件恰好映射到一个输出文件夹。在转换之前已转换过的 QVW 文件时，QV2QS 会在输出根目录中搜索标记与源路径匹配的子文件夹。如果找到匹配项，QV2QS 会复用该文件夹并读取其中的 cloud_state.json。如果未找到匹配项，QV2QS 将创建一个带有数字后缀的新子文件夹。
在向导中，适用相同的匹配逻辑。当启用 重用现有应用程序 时，向导会检查输出文件夹中是否存在匹配的项目，并自动从上一次部署中填充 AppId 字段。如果未找到先前的部署，该字段将保持为空，并接受手动输入或浏览选择器。
.qv2qs_source 标记文件会自动创建。不要编辑或删除该文件。移除该标记会导致 QV2QS 在下次运行时创建新的项目子文件夹，而不是复用现有的子文件夹。
重新部署行为
QV2QS 使用 qlik app build 部署到目标应用程序。构建命令会对应用程序对象模型进行完全替换。构建输出中定义的所有对象都会写入应用程序。构建输出中不存在的对象将被移除。
在运行构建之前，QV2QS 会准备现有工作表以进行替换。QV2QS 针对活动应用程序验证工作表映射（参见 工作表 ID 映射），记录每个工作表的发布状态和排序，并从云应用程序中删除旧工作表。本地构建输出会使用原始 Qlik Sense 工作表 ID 进行修补，以便引用这些 ID 的书签和链接在构建后能够继续正常工作。
构建完成后，QV2QS 会恢复原始工作表状态。先前已发布的工作表将作为基础工作表重新发布，并恢复原始排序（显示顺序）。当启用 发布工作表 设置时，之前部署中不存在的新工作表将作为基础工作表发布。禁用该设置以使新工作表保持未发布状态。
目标应用程序中用户创建的内容（在上次部署后手动添加的工作表、书签、故事或自定义对象）在重新部署期间不会保留。qlik app build 命令将应用程序内容替换为构建输出。如果进行了手动调整，请在重新部署之前备份或发布应用程序。
部署前备份
在复用现有应用程序时，QV2QS 会在修改该应用程序之前自动导出一个无数据 QVF 备份。备份会捕获应用程序结构（工作表、对象、加载脚本和元数据）而不包含数据，因此导出速度很快且文件很小。
备份保存在项目输出文件夹内的 cloud/backups/。每个备份文件均命名为 <AppName>_<shortId>_<timestamp>_nodata.qvf。例如，Sales_a1b2c3d4_20260226-143025_nodata.qvf。
如果备份导出失败（例如，由于网络中断或权限不足），QV2QS 会记录一条警告并继续部署。此失败不会阻止转换。
若要跳过自动备份，请在命令行中传递 --noBackup，或在向导中启用跳过部署前备份。在由外部管理备份的 CI/CD 流水线中，跳过备份非常有用。
保留目标应用程序加载脚本
默认情况下，QV2QS 会将目标应用程序中的加载脚本替换为来自 QlikView 源的已转换加载脚本。使用 --preserveTargetAppScript 保持目标应用程序中现有的加载脚本不变。转换后的加载脚本会写入本地 build/script.qvs 文件，但不会应用到云应用程序。
此选项需要 --appId 或 --reuseAppId，因为它仅在针对现有应用程序时适用。它可以与 --reload 结合使用，以便在更新 UI 后执行现有脚本，这在目标应用程序已具有正常工作的 Qlik Cloud 数据连接时非常有用。它还可以与 --autoBinary 结合使用，以在保持目标脚本完好无损的同时从原始 QVW 文件临时加载数据。
保留目标应用程序变量
默认情况下，QV2QS 会将目标应用程序中的变量替换为来自 QlikView 源的已转换变量。使用 --preserveTargetAppVariables 保持目标应用程序中的现有变量不变。转换后的变量会写入本地 variables.json 文件，但不会应用到云应用程序。
此选项需要 --appId 或 --reuseAppId，因为它仅在针对现有应用程序时适用。它可以与 --preserveTargetAppScript 结合使用，以保持目标应用程序的加载脚本和变量完好无损。