如何让MediaWiki扩展中ResourceModules注册的CSS可引用图片资源

架构老林

2026-10-4

问题

如何将图片添加到MediaWiki扩展中，使其可被注册为ResourceModules的CSS文件引用？

场景说明

我正在开发一个MediaWiki扩展，用到了第三方工具，我将该工具的副本作为扩展资源的一部分引入。
该工具包含js和css，我按如下方式引入：

...
  "ResourceModules": {
    "ext.leaflet": {
      "scripts": "ext.leaflet/leaflet.js",
      "styles": "ext.leaflet/leaflet.css"
    }
  },
...

该第三方工具还包含一个图片目录，里面有leaflet.css引用的各类图片，但我不知道应该将其放在什么位置，才能让MediaWiki将其与CSS/JS一同提供服务。
当前图片URL解析为{SERVER}/ext.leaflet/images/marker-icon.png

解决方案

首先保持第三方工具的原有目录层级，将完整的资源包放在你开发的扩展的resources子目录下，推荐的目录结构如下：

你的扩展目录名/
├── extension.json
└── resources/
    └── ext.leaflet/
        ├── leaflet.js
        ├── leaflet.css
        └── images/
            ├── marker-icon.png
            └── 其他leaflet依赖的图片资源

不需要在ResourceModules配置中额外注册图片资源，只要leaflet.css中引用图片的路径是相对路径（如url('images/marker-icon.png')），MediaWiki的ResourceLoader会自动根据CSS文件的位置匹配对应路径的图片资源。
如果调整目录后仍存在路径解析错误，可以在extension.json的对应资源模块配置中添加localBasePath和remoteExtPath字段明确路径映射，修改后的配置示例如下：

"ResourceModules": {
  "ext.leaflet": {
    "localBasePath": "resources/ext.leaflet",
    "remoteExtPath": "你的扩展目录名/resources/ext.leaflet",
    "scripts": "leaflet.js",
    "styles": "leaflet.css"
  }
}

注意将配置中的你的扩展目录名替换为你实际的扩展文件夹名称。