- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
6.7 KiB
Executable File
6.7 KiB
Executable File
ext/web 定制限制:开发者不易定制的问题盘点
| 状态 | 调研锁定(踩坑整理) |
| 日期 | 2026-09-04 |
| 相关 | ext-web.md · ext-web-net.md · web-net-capabilities.md |
| 解决索引 | ../design/ext-web-customization/ |
结合自研后台、样式迁移与响应式改造中的实际踩坑,整理当前 plugins/web + ext/web 对站点作者的强占与难定制点。本文只陈述问题与证据;逐项解法见解决索引。
0. 一句话
内置 /admin 壳、固定鉴权路径、注入式 SHELL_CSS 与四区栅格,让「只写 .mq.md」的产品路径在自研后台 / 品牌主题 / 移动端上反复撞墙;作者被迫旁路前缀 + !important + 前端 JS 兜底。
1. 路由与路径被框架强占
现象
/admin及/admin/*整段保留,无法app.route注册自定义页(错误:route path … is reserved)。app.重定向/redirect目标若落在 reserved 前缀,同样被校验拒绝。后台=False(admin=False)后,访问/admin/news等仍进内置壳,只显示 Admin is disabled,不能换成自研页。- 登录/登出硬绑
/admin/login、/admin/logout;登录成功硬编码Redirect::to("/admin"),无法配置回跳到/desk。
代码证据
| 位置 | 行为 |
|---|---|
plugins/web/src/lib.rs → normalize_route_path |
/admin、/_form、/_part、/static 一律 reserved |
plugins/web/src/http.rs |
始终挂 /admin… 路由;disabled 时仍 admin_shell + 文案 |
同文件 admin_login_post |
成功跳转写死 /admin |
结果
自研后台只能用 /desk 等旁路前缀;入口与鉴权路径分裂,还要靠前端 JS(fetch('/admin/login') 再 replace('/desk'))做跳转兜底。
→ 解决:01-routes-and-admin-prefix.md
2. 内置 SHELL_CSS 难以彻底覆盖
现象
- 每个页面都会注入框架壳样式,例如
body.has-sidebar { grid-template-columns:14rem 1fr; … }、默认卡片/表单/侧栏色。 - 规则无媒体查询、选择器优先级不低;站点主题选择器不够强时,小屏双列、侧栏占位等「幽灵布局」反复出现。
- 首页有额外 class(如
has-rail)时碰巧盖住,其他页没有同类 class 就暴露——表现为「只修了首页」。 - 实务上经常要
!important+ 更高选择器,与「干净主题层」冲突。
代码证据
| 位置 | 行为 |
|---|---|
plugins/web/src/render.rs → SHELL_CSS |
常量内联进每个 HTML |
| 同文件壳渲染 | <style>{SHELL_CSS}{extra}</style>,主题只能接在后面 |
→ 解决:02-shell-css.md
3. 鉴权 / 门禁模型偏固定
现象
- 未登录访问受保护路径:对
/admin*会 303 → 登录页;对/desk等自定义路径往往是 403 HTML,行为不一致。 - 门禁匹配偏宽:
path.starts_with/path_matches使/desk匹配/desk/login,公开登录页易被误伤。 - 默认鉴权挂上
/admin*→admin;/admin-publish这类名字也会被当成 admin 域(starts_with("/admin"))。 - 会话 cookie、CSRF、登录表单字段均固定在框架实现;难换登录 UI 或改成功落地页。
代码证据
| 位置 | 行为 |
|---|---|
http.rs → rbac_middleware |
visitor + /admin* → redirect;其它 gate → 403 |
http.rs → path_matches |
前缀匹配,无「精确路径 + 子路径排除」DSL |
lib.rs → web_app_auth |
默认塞入 /admin* gate |
→ 解决:03-auth-gates.md
4. 样式作者体验受限
现象
- 样式表是 GFM 表格;含
/的值必须加引号(如"1 / 5"),否则单元格表达式把/当除法(曾出现grid-column变成0)。 @keyframes、复杂选择器、多层媒体查询(min-widthandmax-width)表达能力有限,装配顺序要小心。- 主题 CSS 与
SHELL_CSS同页串联,级联顺序不透明,调试成本高。 - 响应式不能指望框架;壳层几乎不提供移动端抽屉/折叠。
→ 解决:04-stylesheet-authoring.md
5. 页面壳与插槽约定僵硬
现象
- 壳结构固定为
topnav/side/main/foot栅格命名区。 - 侧栏一旦装配,
body即has-sidebar,套上框架双列;杂志风单列、抽屉必须自己拆布局。 - 组件表驱动导航,难做运行时条件导航(小屏合并顶栏+侧栏),通常再补
theme.js。
6. 后台 CRUD 与表单能力边界
现象
- 内置 admin 是通用表管理,不是产品级 CMS;关了又占着
/admin路径(与 §1 叠加)。 - 表单以声明式字段表为主;Markdown 分栏、专栏元数据联动等只能外挂 JS。
- 列表「链接前缀」等约定简单;编辑/新建状态机常靠前端拼(
?id=、?new=1)。
7. 静态资源与脚本生命周期
现象
- 头资源脚本常在
<head>同步加载;若脚本假设 DOM 已就绪会直接失败(登录页曾因此不跳转)。 - 缓存靠
?v=手动 bump;无构建管线时易出现「改了 JS 浏览器仍用旧文件」。
→ 解决:07-assets-script-lifecycle.md
8. 扩展与部署耦合
现象
- 能力依赖 web 插件 ABI / Marqdo 版本(如 0.3.2 起的样式引号约定);升级要同步 Docker / 本机二进制。
- 定制若依赖改插件源码(放宽
/adminreserved、可配置 login redirect),就脱离「只写.mq.md」的产品路径,维护成本陡增。
→ 解决:08-ext-deploy-coupling.md
9. 优先级建议(给实现排期)
| 优先级 | 项 | 理由 |
|---|---|---|
| P0 | §1 路由/前缀 + §3 鉴权一致 | 阻塞自研后台产品路径 |
| P1 | §2 SHELL_CSS + §5 壳布局 | 阻塞品牌主题与响应式 |
| P2 | §4 样式作者体验 + §7 脚本生命周期 | 降低日常踩坑,不改架构也能缓解 |
| P3 | §6 CRUD 边界 + §8 部署耦合 | 文档/约定/可选增强为主 |
详细验收与实现切片见解决索引 README。