====== 支持 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}}