- 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。
155 lines
6.7 KiB
Markdown
Executable File
155 lines
6.7 KiB
Markdown
Executable File
# `ext/web` 定制限制:开发者不易定制的问题盘点
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **调研锁定(踩坑整理)** |
|
||
| 日期 | 2026-09-04 |
|
||
| 相关 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) |
|
||
| 解决索引 | [../design/ext-web-customization/](../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](../design/ext-web-customization/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](../design/ext-web-customization/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](../design/ext-web-customization/03-auth-gates.md)
|
||
|
||
---
|
||
|
||
## 4. 样式作者体验受限
|
||
|
||
**现象**
|
||
|
||
- 样式表是 GFM 表格;含 `/` 的值必须加引号(如 `"1 / 5"`),否则单元格表达式把 `/` 当除法(曾出现 `grid-column` 变成 `0`)。
|
||
- `@keyframes`、复杂选择器、多层媒体查询(`min-width` and `max-width`)表达能力有限,装配顺序要小心。
|
||
- 主题 CSS 与 `SHELL_CSS` 同页串联,级联顺序不透明,调试成本高。
|
||
- 响应式不能指望框架;壳层几乎不提供移动端抽屉/折叠。
|
||
|
||
→ 解决:[04-stylesheet-authoring.md](../design/ext-web-customization/04-stylesheet-authoring.md)
|
||
|
||
---
|
||
|
||
## 5. 页面壳与插槽约定僵硬
|
||
|
||
**现象**
|
||
|
||
- 壳结构固定为 `topnav` / `side` / `main` / `foot` 栅格命名区。
|
||
- 侧栏一旦装配,`body` 即 `has-sidebar`,套上框架双列;杂志风单列、抽屉必须自己拆布局。
|
||
- 组件表驱动导航,难做运行时条件导航(小屏合并顶栏+侧栏),通常再补 `theme.js`。
|
||
|
||
→ 解决:[05-page-shell-slots.md](../design/ext-web-customization/05-page-shell-slots.md)
|
||
|
||
---
|
||
|
||
## 6. 后台 CRUD 与表单能力边界
|
||
|
||
**现象**
|
||
|
||
- 内置 admin 是通用表管理,不是产品级 CMS;**关了又占着 `/admin` 路径**(与 §1 叠加)。
|
||
- 表单以声明式字段表为主;Markdown 分栏、专栏元数据联动等只能外挂 JS。
|
||
- 列表「链接前缀」等约定简单;编辑/新建状态机常靠前端拼(`?id=`、`?new=1`)。
|
||
|
||
→ 解决:[06-admin-crud-forms.md](../design/ext-web-customization/06-admin-crud-forms.md)
|
||
|
||
---
|
||
|
||
## 7. 静态资源与脚本生命周期
|
||
|
||
**现象**
|
||
|
||
- 头资源脚本常在 `<head>` **同步**加载;若脚本假设 DOM 已就绪会直接失败(登录页曾因此不跳转)。
|
||
- 缓存靠 `?v=` 手动 bump;无构建管线时易出现「改了 JS 浏览器仍用旧文件」。
|
||
|
||
→ 解决:[07-assets-script-lifecycle.md](../design/ext-web-customization/07-assets-script-lifecycle.md)
|
||
|
||
---
|
||
|
||
## 8. 扩展与部署耦合
|
||
|
||
**现象**
|
||
|
||
- 能力依赖 web 插件 ABI / Marqdo 版本(如 0.3.2 起的样式引号约定);升级要同步 Docker / 本机二进制。
|
||
- 定制若依赖改插件源码(放宽 `/admin` reserved、可配置 login redirect),就脱离「只写 `.mq.md`」的产品路径,维护成本陡增。
|
||
|
||
→ 解决:[08-ext-deploy-coupling.md](../design/ext-web-customization/08-ext-deploy-coupling.md)
|
||
|
||
---
|
||
|
||
## 9. 优先级建议(给实现排期)
|
||
|
||
| 优先级 | 项 | 理由 |
|
||
|--------|-----|------|
|
||
| P0 | §1 路由/前缀 + §3 鉴权一致 | 阻塞自研后台产品路径 |
|
||
| P1 | §2 SHELL_CSS + §5 壳布局 | 阻塞品牌主题与响应式 |
|
||
| P2 | §4 样式作者体验 + §7 脚本生命周期 | 降低日常踩坑,不改架构也能缓解 |
|
||
| P3 | §6 CRUD 边界 + §8 部署耦合 | 文档/约定/可选增强为主 |
|
||
|
||
详细验收与实现切片见解决索引 README。
|