如何使用Resources Importer完成不同版本Liferay的模板与结构迁移

前置准备 #

• 先从旧版本 Liferay 中导出所有需要迁移的结构（Structure）和模板（Template）的原始定义：结构导出为 JSON 格式，模板导出为对应的 ftl/vm 等原生格式，不要使用 Lar 导出包
• 确认目标新版本 Liferay 的 Resources Importer 插件已正常启用，对应站点的权限配置完成，你拥有站点管理员级别权限
• 准备一个空白的主题模块或者 Resources Importer 专属模块，该模块仅用来承载迁移资源，不需要额外开发业务逻辑

核心操作步骤 #

1. 构造资源目录结构 #

在你的迁移模块的src/main/resources/META-INF/resources目录下按照固定格式创建目录：

resources-importer/
├── journal/
│   ├── structures/
│   │   ├── 你的结构名称1.json
│   │   ├── 你的结构名称2.json
│   └── templates/
│       ├── 你的模板名称1.ftl
│       ├── 你的模板名称2.ftl
├── assets.json

注意：结构文件名和模板文件名不要包含特殊字符、空格，结构和模板的对应关系需要在 assets.json 中明确声明

2. 编写 assets.json 配置文件 #

该文件用来定义资源的映射关系、权限、关联属性，基础示例如下：

{
  "availableLocales": ["zh_CN", "en_US"],
  "defaultLocale": "zh_CN",
  "journalStructures": [
    {
      "name": "文章结构1",
      "description": "从旧版本迁移的文章结构",
      "structureKey": "ARTICLE_STRUCTURE_1",
      "file": "structures/你的结构名称1.json",
      "journalTemplates": [
        {
          "name": "文章详情模板1",
          "description": "从旧版本迁移的文章详情模板",
          "templateKey": "ARTICLE_TEMPLATE_1",
          "file": "templates/你的模板名称1.ftl",
          "language": "ftl"
        }
      ]
    }
  ]
}

注意：structureKey 和 templateKey 建议沿用旧版本 Liferay 中的对应值，避免后续关联内容出现映射错误

3. 配置模块的 liferay-plugin-package.properties #

在模块的配置文件中添加 Resources Importer 相关配置，指定要导入的目标站点：

resources-importer-target-class-name=com.liferay.portal.kernel.model.Group
resources-importer-target-value=[你的目标站点ID或者站点友好URL]
resources-importer-developer-mode-enabled=false

如果不知道目标站点 ID，可以在站点设置的通用信息页面查看

4. 执行资源导入 #

• 将开发完成的迁移模块部署到新版本 Liferay 的部署目录下，等待模块自动启动
• 模块启动完成后进入目标站点的「内容与数据」-「Web内容」页面，查看结构和模板是否已经正常导入
• 验证模板的渲染逻辑是否正常，结构的字段配置和旧版本是否完全一致

问题排查 #

• 如果导入失败，优先查看 Liferay 的日志文件，常见错误为 JSON 格式错误、模板语法不兼容新版本的 Liferay 标签库
• 如果出现结构字段缺失，检查导出的 JSON 是否包含所有字段定义，不要包含旧版本专属的废弃字段
• 如果模板渲染异常，需要将旧版本中使用的过时 API 替换为新版本 Liferay 提供的对应 API

内容的提问来源于stack exchange，提问作者ali