====== 支持 PWA:把 DokuWiki 装成独立应用 ======
===== 背景问题 =====
在手机上打开站点内的工具页时,浏览器地址栏与标签栏会占去相当一部分屏幕。希望达到的效果是:桌面点开图标即进入该页,界面中没有地址栏,看上去与普通应用无异。
这并不需要另做一套原生应用。浏览器自带的「安装」能力——渐进式 Web 应用(Progressive Web App,下称 PWA)——已经能满足:安装后以独立窗口打开站点。真正需要解决的问题不是「能不能装」,而是「装出来的东西是不是想要的样子」:打开哪一页、有没有顶栏与侧栏、桌面图标是否耐看、手机上排版是否正常。以下按这几个问题逐项记录实践与判据。
===== 核心自带了什么 =====
DokuWiki 自 2018-04-22a 起内置 [[doku>devel:manifest|Web App Manifest]] 支持,本文环境为 2026-07-14c,机制未变:
* 生成入口是 ''lib/exe/manifest.php'' 与 ''inc/Manifest.php'';模板的 head 里自动输出 %%%%。若在 ''disableactions'' 里加入 ''manifest'',该入口即关闭。
* 配置走文件级联:''conf/manifest.json''(镜像内只有 %%{"display":"standalone"}%%)→ ''conf/manifest.local.json'' 覆盖。多实例(farm)环境中,local 文件位于 %%farm/<实例名>/conf/manifest.local.json%%。
* 未显式指定的字段:''name'' / ''short_name'' / ''description'' 取自站点 ''title'' 与 ''tagline'';''start_url'' 默认为站点根;''scope'' 被强制为站点根;背景色与主题色取自模板 ''style.ini'' 的 ''__background__'' 与 ''__theme_color__''。
* **没有 service worker**。因此「可安装、可全屏」成立,「断网仍可打开」不成立。第三方的 ''pwaoffline'' 插件可补这一环,但它自 2019 年后未再更新,且默认把整站页面缓存给每一个访客,公网 wiki 并不划算。
===== 能不能装:用浏览器自己的判据 =====
判断可安装性不应凭感觉,Chrome 提供了两个可直接查询的接口(通过 DevTools 协议调用):
cdp('Page.getAppManifest') # 返回 manifest 的 url、errors 与解析结果(display / startUrl / icons)
cdp('Page.getInstallabilityErrors') # 返回错误列表,空列表即可安装
本站在补齐图标之前,只报出两条错误,且都与图标有关:
manifest-missing-suitable-icon (minimum-icon-size-in-pixels: 144)
no-acceptable-icon (minimum-icon-size-in-pixels: 144)
值得注意的是,错误列表里**没有任何与 service worker 相关的条目**——当前版本的 Chrome 并不因缺少 service worker 而拒绝安装。换言之,「装不上」几乎总是图标不够大。
===== 图标:从 16 像素到 512 像素 =====
核心自动挑选的图标只有两类,且都不合用:
* '':wiki:favicon.ico'',清单里标注尺寸为 16x16;
* '':wiki:logo.svg''、'':logo.svg''、'':wiki:dokuwiki.svg'',标注为 17x17 512x512 的 SVG。
* ''_media'' 里普通的 PNG logo **不会被自动选用**,即使放的是一张 512 像素的图片,manifest 里依然没有图标。
* 自动图标的地址跟随 ''baseurl'' 生成。本站输出的是 http://blog.zhao-99.uk/_media/wiki:favicon.ico:与访问域名不同、且是 http,在 https 页面中根本无法加载。
因此自定义图标必须写进 ''manifest.local.json'',并且使用根相对路径或完整地址,不要依赖自动值。
**先量源图,再谈放大**。判断一张图能否作为图标,只需读三个量:四边的不透明像素数与内容包围盒(bounding box):
im = Image.open('logo.png').convert('RGBA'); px = im.load(); W, H = im.size
row = lambda y: sum(1 for x in range(W) if px[x, y][3] > 20)
col = lambda x: sum(1 for y in range(H) if px[x, y][3] > 20)
print(row(0), row(H - 1), col(0), col(W - 1)) # 四边不透明像素数
若某一边的数值明显不为零,且包围盒偏在一角,说明这张图是被裁切的局部而非完整标志。放大到 512 只会把缺口一并放大,桌面图标会显得歪斜;这种情况应当另找矢量源,而不是硬放大。
图标源的几个可靠出处(均可商用、无需署名):
^ 图标集 ^ 许可 ^ 取法 ^
| Material Symbols(Google) | Apache-2.0 | %%api.iconify.design/material-symbols/.svg%% |
| Bootstrap Icons | MIT | %%api.iconify.design/bi/.svg%% |
| Tabler Icons | MIT | %%api.iconify.design/tabler/.svg%% |
| Lucide | ISC | %%api.iconify.design/lucide/.svg%% |
选图以实心剪影为宜:描边风格在 192 像素下会细碎到难以辨认。尺寸上至少准备 192 与 512 两张,另加一张 ''purpose: maskable'' 的版本(主体缩到画布的 56% 左右,落在安卓圆形遮罩的安全区内)。
SVG 转 PNG 不需要额外工具,本机有 Chrome 即可(去掉 ''--default-background-color'' 会得到白底,保留则为透明底):
google-chrome --headless --disable-gpu --no-sandbox --hide-scrollbars \
--default-background-color=00000000 --window-size=1024,1024 \
--screenshot=out.png "file:///tmp/wrap.html"
===== manifest 改在哪里 =====
''manifest'' 不是普通的 ''$conf'' 配置项:配置管理器的选项元数据里搜不到它,''Manifest.php'' 用的是 ''retrieveConfig('manifest', 'jsonToArray')'',即文件级联。所以「管理 → 配置设置」里找不到对应开关,这是设计使然——它需要容纳 ''icons'' 这种嵌套数组。
已安装的 **Advanced DokuWiki** 插件(作者 Giuseppe Di Terlizzi)提供了编辑入口:后台的 Advanced 面板 → Configurations 标签 → 左侧 Manifest。它取的文件正是 ''$config_cascade['manifest']['local'][0]'',也就是上面那份 ''manifest.local.json'';右侧可对照镜像自带的默认值。
两点需要留意:
* 它是纯文本编辑器,**不校验 JSON**。少一个逗号就能让整份 manifest 失效:页面 head 里的 link 仍在,但浏览器解析失败,安装能力随之消失。改完务必回到上面那两条浏览器判据复验。
* 它只作用于当前实例的 ''conf''。多实例环境下,其余实例需要各自一份。
iOS 的主屏图标不走 manifest,而走模板函数 ''tpl_favicon('mobile')'',其查找顺序为 '':wiki:apple-touch-icon.png'' → '':apple-touch-icon.png'' → 模板自带的 ''images/apple-touch-icon.png''。因此上传一张 180×180 的图到媒体目录 ''wiki:apple-touch-icon.png'',即可顶替模板自带的图标。
===== 让它打开就是某一页 =====
安装目标页由 ''start_url'' 决定。只想「点开就是这一页」时,改 ''start_url'' 即可,''scope'' 仍为整站——安装后仍可在窗口内导航到其他页面。
若要「只锁住那一页」,单靠 manifest 做不到:''scope'' 只接受路径前缀,不支持 ?id=xxx 这类带查询的地址。可行的替代是给一个独立的静态页(例如 ''/pages-html/tool.html'')单独准备一份 manifest 与入口,代价是它与 wiki 的访问控制彼此独立。
还有一处容易忽略:不写 ''id'' 时,浏览器以 ''start_url'' 作为应用标识。改动 ''start_url'' 等于换了一个应用,先前的安装项不会自动更新,需要手动删除后重装。
===== 页面自身的减法 =====
安装只是去掉地址栏,模板的顶栏、侧栏与页脚仍在。侧栏可以按页关闭:站内装有 ''nosidebar'' 插件,在页面源码顶格加一行
~~NOSIDEBAR~~
该页的侧栏即消失,其余页面不受影响(机制是在页面元数据中置位,并在模板输出前清空 ''$conf['sidebar']'';判据是渲染后 body 的 class 中不再含 ''sidebar'')。
顶栏与页脚没有等价的内置开关。用 ''?do=export_html'' 打开裸页可以去掉它们,但 export 输出的 head 中**没有 %%%%**:手机浏览器会按 980 CSS 像素布局再整体缩放,正文因此显著偏小(实测在 390 像素视口下 ''innerWidth'' 仍报 980)。所以移动端不宜以裸页作为入口;要么保留正常模板页只关侧栏,要么使用自带 viewport 的静态页。
===== 验收清单 =====
每次改动 manifest 或图标后,按下面的顺序确认,缺一项都不算完成:
1. %%curl https://<域名>/lib/exe/manifest.php%%:icons 数组齐全、''start_url'' / ''display'' 与预期一致;
2. 逐个 ''curl -I'' 图标地址:状态 200、类型 image/png、体积合理;
3. ''Page.getAppManifest'':''errors'' 为空,解析后的 ''startUrl'' 正确;
4. ''Page.getInstallabilityErrors'':返回空列表;
5. 手机视口(例如 390 像素)下确认 ''innerWidth'' 等于视口宽度,版面不自适应即说明缺少 viewport 声明;
6. 目标页的 body class 中确认侧栏已去除。
本实例的最终配置如下,可作为参照:
{
"name": "水文干旱综合指数计算",
"short_name": "干旱指数",
"start_url": "/doku.php?id=zh:hydrology:drought_index",
"scope": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#ffffff",
"lang": "zh-CN",
"icons": [
{"src": "/pages-html/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any"},
{"src": "/pages-html/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any"},
{"src": "/pages-html/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}
]
}
===== 结论 =====
DokuWiki 的 PWA 支持是「半套」:manifest 齐备、安装链路可用,但没有 service worker,因此只能解决「像应用一样打开」,不能解决「断网可用」。在这半套能力上做到可用,关键只有三件事——图标够大且来源干净、''start_url'' 指向真正要展示的页面、manifest 用浏览器自带的判据复验。
^ 目标 ^ 做法 ^ 代价 ^
| 打开即是某一页 | 改 ''start_url'' | 窗口内仍可导航全站 |
| 只停留在单页 | 给独立静态页单独做 manifest | 与 wiki 的访问控制彼此独立 |
| 去掉左侧栏 | 页面加 ''~~NOSIDEBAR~~'' | 仅按页生效,无「仅 App 内」开关 |
| 去掉顶栏页脚 | 以 ''?do=export_html'' 作入口 | export 页缺 viewport,移动端字号偏小 |
| 断网可用 | 需 service worker(核心没有) | 第三方插件已停更,公网站点不划算 |
{{tag>dokuwiki pwa}}