Question 1

为什么通过脚手架新建的 content-editor 插件 lint 失败，报错 "contentAccess is required when any cms.content.* permission is granted"？

Accepted Answer

脚手架会将 `contentAccess` 写入插件配置，但 `definePlugin` 的 `DefinePluginConfig` 类型中没有 `contentAccess` 键，且其 manifest 组装过程也从不转发它，因此该键会被静默丢弃，而生成的 `cms.content.*` 权限仍然需要它。临时解决方案：在运行 `instatic-plugin lint` 或构建之前，将 `contentAccess` 重新注入到组装后的 manifest 中——例如，对一个一次性副本进行 lint/构建，其配置对 manifest 进行后处理以添加 `contentAccess: [{ table: 'pages', modes: ['read', 'write'] }]`，从而使仓库源码保持不变。永久修复：在 `definePlugin.ts` 的 `DefinePluginConfig` 中添加 `contentAccess`，并在 manifest 组装过程中转发它，使脚手架无需修改即可通过 lint。

Question 2

为什么在构建后的样式表中,我的 min-width 媒体查询被更小的断点覆盖了?

Accepted Answer

构建器以最大优先的顺序输出 min-width 媒体查询块（例如 @media (min-width: 1024px) 排在 @media (min-width: 768px) 之前），因此当特异性相同时，源码顺序会让较窄的 768px 块在所有超过 1024px 的视口中生效——移动优先的 CSS 实际上被颠倒了。可以通过 site_read_styles 读回规则或检查构建后的样式表来验证：存储的 CSS 看起来与编写的完全一致，但输出顺序是反的。在补丁发布之前的变通方法：不要在相同特异性下将同一属性拆分到多个 min-width 断点中——将所有桌面端覆盖合并到单个最小的桌面断点中，或者提高较宽断点规则的特异性，使源码顺序不再决定哪条规则胜出。永久修复方案是在构建时对输出的上下文进行排序：min-width 升序，max-width 降序。

Question 3

为什么公开表单提交时 content.entry.created 插件事件不会触发，以及如何解决？

Accepted Answer

公共表单处理器（`server/forms/handler.ts`）通过 `createDataRow(...)` 创建数据行，但之后从未调用 emit 辅助函数，这与管理员写入路径（`server/handlers/cms/data/tables.ts:344`、`rows.ts:190/220/239`）不同。修复方案 1（最小改动）：在公共路径上创建数据行后立即调用 `emitContentEntryCreated(db, row.id, { kind: 'system' })`。修复方案 2（更适合表单专属插件）：添加一个专门的 `forms.submission.created` 核心事件，携带 `{ formId, pageId, tableSlug, entryId }`。在补丁修复之前，插件端的临时解决方案：在前端资源中包装 `window.fetch` 以监听提交响应，并运行定时的对账清理扫描，作为禁用 JavaScript 的访客的兜底方案。

Question 4

为什么插件 FrontendAsset 的 `attrs` 会丢弃 `type`、`rel` 和 `href`？我到底该如何输出 JSON-LD 结构化数据（`application/ld+json`）？

Accepted Answer

原因：`server/publish/frontendInjections.ts` 中的 `formatAttrs` 全局保留了 `src`、`href`、`rel`、`type`、`defer`、`async` 和 `data-plugin-id`，因此 `attrs` 中的这些键会被静默剥离。唯一会输出 `type` 的代码路径是 `strategy: 'module'`，而它仅存在于 `kind: 'script'` 上——内联脚本和 `kind: 'link'` 都没有途径使用这些属性，因此文档中记录的 `{ "kind": "link", "attrs": { "rel": "preconnect", "href": "..." } }` 示例会渲染成一个空的 ``。 JSON-LD 的变通方案：声明一个经典的内联脚本，并在运行时注入 JSON-LD 节点，而不是依赖 `attrs.type`： ```ts { kind: 'script-inline', placement: 'head-end', content: `var s=document.createElement('script');s.type='application/ld+json';s.textContent=JSON.stringify({"@context":"https://schema.org","@type":"Article"});document.head.appendChild(s);` } ``` Googlebot 会渲染 JavaScript 并获取动态注入的结构化数据，因此这种方式的验证效果与静态标签相同。请注意，只要存在内联脚本资源，页面 CSP 就已经放宽为 `script-src 'self' 'unsafe-inline'`，因此无需额外的 CSP 更改。对于 ``，没有在 manifest 内的变通方案——两个键都被保留，而 `kind: 'link'` 分支不会补回任何内容。永久修复方案（在 issue #392 中跟踪）是按 kind 进行属性保留：`src` 仅在 `script` 上保留，`href`/`rel` 仅在 `link` 上保留，`type` 仅在设置了 `strategy: 'module'` 时保留。

Question 5

为什么通过 JavaScript 切换的 CSS 类在发布后会从样式表中消失？

Accepted Answer

发布步骤会裁剪任何其类名未附加到创作文档中节点的 CSS 规则——包括那些仅在运行时通过 JS 切换才存在的修饰符类（例如 `.mobilenav--open`）。该规则在发布前可以通过 `site_read_styles` 正确读取，但在发布后的样式表中被移除，因此无论脚本如何操作，元素始终保持其基础状态（例如 `display: none`）。解决方法：（1）在创作文档中保留对该类的引用——将修饰符类附加到至少一个节点（即使是一个隐藏的占位元素），这样裁剪器会将其视为已使用，该规则就能在发布后保留。（2）在脚本中以行内样式的方式应用运行时状态，而不是切换类（例如 `el.style.display = 'flex'`）——这样做可行，但会失去层叠能力：该状态无法使用媒体查询、伪状态或主题。诊断方法：将 `site_read_styles` 的输出与发布的样式表进行 diff 对比；任何存在于前者但不存在于后者的规则都是被裁剪掉的。

Instatic

核心功能

避坑指南

适用场景

标签

快速上手

相似推荐