preview-import

用途

Preview Import 用于在本地 AEM Edge Delivery Services 开发服务器中打开并验证已导入的内容。它属于页面导入工作流的一环，由 page-import 技能在第 5 步调用，主要目标是让用户在浏览器中预览渲染结果、与原始页面进行对比，并排查常见问题。

何时使用

当满足以下情况时使用本技能：

已通过 generate-import-html 生成 HTML 文件
准备在浏览器中预览并验证渲染效果
需要与原始页面结构进行对比

前置条件

来自此前技能，需要具备：

位于正确路径的 HTML 文件（来自 generate-import-html）
同一目录下的 images 文件夹
来自 scrape-webpage 的 screenshot.png（用于对比）
来自 metadata.json 的 documentPath（用于构造 URL）

预览工作流

第 1 步：启动开发服务器

命令：

aem up

这会在 http://localhost:3000 启动本地 AEM 代理服务器。

第 2 步：在浏览器中导航

对于大多数文件，直接使用文档路径：

http://localhost:3000${documentPath}

示例：

HTML 文件：us/en/about.plain.html

URL：http://localhost:3000/us/en/about

重要：对于 index 文件，使用 /index 而非 /：

如果文件是：index.plain.html

预览地址：http://localhost:3000/index

而不是：http://localhost:3000/

注意：如果使用了 --html-folder 标志（例如 aem up --html-folder drafts），需将该文件夹前置到 URL 中：

文件：drafts/test.plain.html

URL：http://localhost:3000/drafts/test

使用 metadata.json 中的 paths.documentPath，但对于 index 文件要确保路径是 /index 而非 /。

第 3 步：验证渲染

检查以下各项：

区块以正确的样式渲染
布局与原始页面结构匹配（与 screenshot.png 对比）
图片加载正常（或显示适当的占位符）
没有可见的原始 HTML
元数据出现在页面源代码中（查看源代码，检查 <meta> 标签）
区块样式正确应用

第 4 步：与原始页面对比

并排对比：

将 ./import-work/screenshot.png 与浏览器预览并排打开
检查内容结构是否匹配
验证区块装饰是否正确
确认区块边界对齐
验证样式一致性

故障排查

区块渲染不正确：

检查 HTML 结构是否符合预期格式
验证区块名称完全匹配（区分大小写）
查阅 ../page-import/resources/html-structure.md 获取格式指导

图片未加载：

验证 images 文件夹与 HTML 文件位于同一目录
检查图片路径是否为 ./images/... 格式
确保图片已从 ./import-work/images/ 正确复制

可见原始 HTML：

区块名称可能与项目中现有区块不匹配
检查浏览器控制台是否有 JavaScript 错误
验证区块存在于 blocks/ 目录中

元数据未出现在页面源代码中：

检查元数据块是否位于 HTML 文件末尾
查看页面源代码并在 <head> 中搜索 <meta> 标签
验证元数据属性是否符合预期格式

开发服务器未运行：

使用 aem up 启动服务器
检查端口冲突（默认 3000）
验证是否处于正确的项目目录

页面未找到（404）：

验证 HTML 文件存在于预期路径
检查 metadata.json 中的 documentPath 是否与 URL 匹配
对于 index 文件，使用 /index 而非 /
如果使用了 --html-folder，需在 URL 中包含该文件夹

输出

本技能提供：

与原始页面结构匹配的已验证预览
正确渲染的视觉确认
已验证的区块装饰
已确认的元数据存在

当所有验证点通过时，导入完成。

技能介绍

用途