📦 模块资源发布

模块安装时会按 Resources/publish-manifest.json 把源码、运行包、装修链接、uni-app 页面片段发布到主工程。本页是 publish-manifest.json 的完整字段参考。模块的安装命令、运行时与运行包关系详见 模块安装与运维；module.json 描述详见 模块配置。

🎯 本页目标

读完本章节后，应能掌握：

• 资源清单 publish-manifest.json 各字段的作用与写法。
• 模块源码、运行包、装修链接、uni-app 页面如何被合并到主工程。
• 不同终端（Admin / H5 / 微信小程序 / App）对模块运行的限制。
• 何时使用 cleanup 清理历史路径、何时使用 retiredSubPackageRoots 清理历史分包。

📍 文件位置

资源清单默认放在：

modules/{Module}/Resources/publish-manifest.json

如果模块 module.json 中通过 resources 字段指定了其他路径，以该字段为准。

🧾 示例结构

{
  "files": [
    {
      "from": "admin/src/views/{Module}",
      "to": "frontend/admin/src/views/{Module}"
    },
    {
      "from": "uniapp/src/modules/{module}",
      "to": "frontend/uniapp/src/modules/{module}"
    },
    {
      "from": "runtime/admin",
      "to": "public/modules/{module}/admin"
    }
  ],
  "cleanup": [
    "frontend/uniapp/src/pages/{module}"
  ],
  "admin": {
    "app_links": [
      {
        "group": "模块名称",
        "path": "/modules/{module}/pages/index",
        "name": "模块首页"
      }
    ],
    "runtime_components": {
      "{Module}/pages/index": "/modules/{module}/admin/pages/index.js"
    }
  },
  "uniapp": {
    "decoration_widgets": [
      {
        "name": "module-goods",
        "component": "@/modules/{module}/components/decoration/GoodsWidget.vue"
      }
    ],
    "retiredSubPackageRoots": [
      "pages/{module}"
    ],
    "subPackages": [
      {
        "root": "modules/{module}/pages",
        "pages": [
          {
            "path": "index",
            "style": {
              "navigationStyle": "custom"
            }
          }
        ]
      }
    ]
  }
}

📁 files

files 是源码发布规则。from 相对于模块 Resources 目录，to 相对于项目根目录。

资源发布会直接写入目标目录。安装模块前，应确认 PHP 运行用户对 to 指向的目录有写入权限；覆盖安装或卸载时，还需要具备删除旧文件的权限。权限不足时，安装器会停止并提示发布路径不可写、无法复制文件或删除后仍有残留。

常见发布目标：

类型	推荐目标
Admin 页面	frontend/admin/src/views/{Module}
Admin 模块装修组件	frontend/admin/src/views/{Module}/component/decoration/widgets/{widget}
uni-app 模块资源	frontend/uniapp/src/modules/{module}
uni-app 模块页面	frontend/uniapp/src/modules/{module}/pages
uni-app 模块私有 API	frontend/uniapp/src/modules/{module}/apis
uni-app 模块私有组件	frontend/uniapp/src/modules/{module}/components
uni-app 模块 Store	frontend/uniapp/src/modules/{module}/stores
uni-app 模块类型	frontend/uniapp/src/modules/{module}/types
uni-app 模块常量	frontend/uniapp/src/modules/{module}
Admin 运行包	public/modules/{module}/admin
H5 运行包	public/modules/{module}/h5

🧹 cleanup

cleanup 用于声明安装或卸载时需要删除的历史发布路径。路径必须是项目内相对路径，不能使用绝对路径或 ..。

当模块发布路径调整后，可以通过该字段清理历史目录，避免 --force 安装后主工程同时保留多套页面。

cleanup 删除的是项目中的真实文件或目录。若历史目录由 root 或其他用户创建，而当前 PHP 运行用户无删除权限，卸载或覆盖安装可能失败，或出现发布目录残留。生产环境应保持 frontend/admin、frontend/uniapp、public/modules 等发布目录的所有者与 PHP 运行用户一致。

🔗 admin.app_links

admin.app_links 会合并生成：

frontend/admin/src/modules/app-links.ts

后台装修链接选择器读取该文件，把已安装模块的用户端页面加入可选链接。group 建议使用模块显示名称，方便链接选择器按模块归类。

🧩 admin.runtime_components

admin.runtime_components 用于生产环境的 Admin 模块运行包。安装器会按已启用模块生成：

frontend/admin/src/modules/runtime-components.ts

Admin 动态路由加载页面时，优先使用已打包进主 Admin 的本地组件；本地组件不存在时，再按 runtime_components 中的入口地址加载模块运行包。运行包加载流程与构建命令详见 模块安装与运维 / 运行时与运行包关系。

推荐写法：

{
  "files": [
    {
      "from": "runtime/admin",
      "to": "public/modules/{module}/admin"
    }
  ],
  "admin": {
    "runtime_components": {
      "{Module}/order/index": "/modules/{module}/admin/order/index.js"
    }
  }
}

运行包入口应导出 Vue 组件，默认导出优先：

export default PageComponent

📱 uniapp.pages / uniapp.subPackages

uniapp.pages 会合并进主包页面列表，uniapp.subPackages 会合并进分包页面列表：

frontend/uniapp/src/pages.json

未安装模块时，主工程 pages.json 不包含该模块页面；安装模块后，安装器再把页面片段写入。模块安装推荐使用 subPackages 分包，分包 root 指向 modules/{module}/pages，方便卸载时按分包根目录移除，也有利于控制微信小程序主包体积。

如果模块需要清理历史分包 root，可以在 uniapp.retiredSubPackageRoots 中声明。安装器同步 pages.json 时会把这些 root 当作模块历史配置移除，避免无效分包继续留在主工程。

🧱 uniapp.decoration_widgets

uniapp.decoration_widgets 用于声明模块在用户端装修页面中可渲染的组件。安装器会按已安装且启用的模块生成：

frontend/uniapp/src/modules/decoration-widgets.ts
frontend/uniapp/src/modules/DecorationWidgetsRender.vue

主工程的 frontend/uniapp/src/components/decoration/DecorationRender.vue 读取这两个入口，判断当前装修项是否由模块组件渲染。模块卸载或停用后，安装器会重新生成入口文件，未启用模块的组件不会被主工程引用。

推荐写法：

{
  "uniapp": {
    "decoration_widgets": [
      {
        "name": "module-goods",
        "component": "@/modules/{module}/components/decoration/GoodsWidget.vue"
      }
    ]
  }
}

字段说明：

字段	说明
name	装修数据中的组件名称，需要和 Admin 装修组件输出的 widget.name 一致
component	uni-app 组件路径，建议使用 @/modules/{module}/... 指向模块发布后的源码

这两个生成文件属于安装器输出，不应手动维护。模块自己的组件源码应放在 modules/{Module}/Resources/uniapp/src/modules/{module}，再通过 files 发布到 frontend/uniapp/src/modules/{module}。

📡 生产端运行限制

Admin 是浏览器 SPA，可以通过模块运行包加载未打进主包的页面。H5 端也运行在浏览器中，可以发布 H5 运行包或容器页，但需要模块自行保证路由、样式和资源地址稳定。

⚠️ 重要：小程序与 APP 原生包不支持热装新页面

微信小程序和 APP 原生包不能在安装模块后动态执行新的远程页面 JS。安装器仍会同步源码和 pages.json，但这些平台必须重新编译、发布或按平台规则更新后，新页面才能进入运行时。

业务上线时，规划安装模块的小程序和 APP 版本要提前完成对应平台的发布流程，不能依赖"线上安装一个模块用户就能马上看到新页面"的预期。

👤 页面访客访问

uni-app 页面默认需要登录。允许游客访问的页面，在页面项上声明 "guest": true：

{
  "path": "pages/system/index/index",
  "guest": true,
  "style": {
    "navigationStyle": "custom"
  }
}

模块页面同样遵循该规则。未声明 "guest": true 的模块页面会按登录页面处理，不需要额外维护登录保护清单。