目录

支持 PWA:把 DokuWiki 装成独立应用

背景问题

在手机上打开站点内的工具页时,浏览器地址栏与标签栏会占去相当一部分屏幕。希望达到的效果是:桌面点开图标即进入该页,界面中没有地址栏,看上去与普通应用无异。

这并不需要另做一套原生应用。浏览器自带的「安装」能力——渐进式 Web 应用(Progressive Web App,下称 PWA)——已经能满足:安装后以独立窗口打开站点。真正需要解决的问题不是「能不能装」,而是「装出来的东西是不是想要的样子」:打开哪一页、有没有顶栏与侧栏、桌面图标是否耐看、手机上排版是否正常。以下按这几个问题逐项记录实践与判据。

核心自带了什么

DokuWiki 自 2018-04-22a 起内置 Web App Manifest 支持,本文环境为 2026-07-14c,机制未变:

能不能装:用浏览器自己的判据

判断可安装性不应凭感觉,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 像素

核心自动挑选的图标只有两类,且都不合用:

因此自定义图标必须写进 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/<name>.svg
Bootstrap Icons MIT api.iconify.design/bi/<name>.svg
Tabler Icons MIT api.iconify.design/tabler/<name>.svg
Lucide ISC api.iconify.design/lucide/<name>.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;右侧可对照镜像自带的默认值。

两点需要留意:

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 中没有 <meta name="viewport">:手机浏览器会按 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 的访问控制彼此独立
去掉左侧栏 页面加 仅按页生效,无「仅 App 内」开关
去掉顶栏页脚 以 ?do=export_html 作入口 export 页缺 viewport,移动端字号偏小
断网可用 需 service worker(核心没有) 第三方插件已停更,公网站点不划算