Repository navigation
Troubleshooting
本文适用于 MarkBridge 1.2.0。第一次导入请先看快速开始。遇到错误时，先复制未保存的正文；不要立即刷新或关闭窗口。MarkBridge 的校验错误会阻止保存，处理后需要重新预览或再次保存。
这个入口位于 文章 → 新建文章 的区块编辑器顶部。已有文章请使用底部 Markdown 编辑 / 上传；也可以从 工具 → Markdown 编辑桥 打开。
若工具菜单也没有入口，请让管理员确认插件已启用、转换运行环境已配置，以及当前账号有编辑权限。安装和服务器配置见安装与升级，普通作者不需要自行构建插件。
新文章的标题或正文已有输入时，顶部导入入口会阻止导入。先保存已有内容，再另开一篇空白新文章；只在确实不需要这些内容时清空后导入。
“文件已读取，尚未保存”是正常提示。选择文件只是把正文填入窗口。还需要填写 标题、稳定文档 ID，选择 保存为 → 草稿，点击 查看差异与预览 → 确认保存草稿。成功后会自动跳到文章编辑器。
文件名、正文一级标题和 front matter 不会自动填入 WordPress 标题。若显示乱码，请把文件另存为 UTF-8 后重试。
ID 需为 3–64 个字符，以英文字母开头，其他字符仅限英文字母、数字、下划线和连字符。例如 first-markdown-post，不要使用中文、空格或以数字开头。
如果提示“文档ID已存在”，先检查是否已保存过这篇文章。需要修改原文章时，从 文章 → 所有文章 或编辑桥列表打开它；需要新建另一篇时，使用不同 ID。不要通过更换 ID 来覆盖或替代原文章。
上传文件上限是 1,500,000 字节，不是 1.5 MiB。服务器也会检查正文、区块和整个请求的大小；接近文件上限时，请求仍可能因额外数据超限。
将长稿分成内容独立的文章，或精简后再导入。每篇新文章使用独立文档 ID。不要把图片编码为大段文本嵌入文件；通过媒体库上传图片，再在正文使用可访问的图片 URL。
确认预览已经显示“校验通过”。如果窗口有错误，先处理错误；如果预览后改过标题、正文或状态，请重新点击 查看差异与预览。
文件来源文章只读、未解决的版本冲突或仍在处理中的请求也会停用保存。普通区块编辑完成后，可直接使用文章编辑器的保存／更新按钮。
新文章公开／私密发布需要有效的特色图片。先将导入内容保存为草稿，进入区块编辑器，在右侧文章设置中选择 特色图片，再发布。Markdown 正文里的图片不能代替封面；工具页的导入窗口没有封面选择器。
没有发布权限时，保存为 只提供 草稿 和 待审核。保存草稿或提交审核，请有发布权限的人继续处理。
文件导入不会上传附件、复制图片文件或将本地相对路径改成媒体库 URL。先通过 WordPress 媒体库上传图片，再把 Markdown 图片地址替换为媒体库提供的 URL，重新预览并保存。已有网页图片还需确认 URL 可访问，且不会因权限或失效地址而无法加载。
MarkBridge 只接受能安全转换并往返的内容，不能保证任意第三方区块或 HTML 都可保存。先保留自己的修改，再把刚加入的复杂区块或样式改为支持的段落、列表、表格等，重试保存。
公式、任务列表和脚注的具体限制见编辑与发布。不要为了通过校验直接删除不理解的内容，必要时把错误信息和复现步骤交给管理员。
服务器文章或绑定源文件在你编辑期间发生了变化。窗口会显示 版本冲突：核对服务器与当前候选，并停用保存。
- 点击 下载当前候选 .md 保留修改；若当前候选尚不能转换为 Markdown，请复制重要文字并保留当前编辑页。
- 点击 重新读取服务器最新版，比较服务器与候选的标题、状态和正文。
- 点击 保留我的修改，基于最新版继续 后，核对并手动合并需要保留的内容。
- 重新点击 查看差异与预览，确认后保存。
“基于最新版继续”不会自动合并正文，也不会自动保存。直接刷新可能丢失未保存内容。
这份文件曾是该文章的历史版本，而服务器已有更新。不要反复上传同一个旧文件来覆盖当前内容。先打开原文章，核对最新版，再通过 Markdown 编辑合并需要的内容；要恢复旧稿，使用 历史版本 / 恢复 并检查预览。
这通常是管理员另行绑定的服务器文件来源文章，与电脑上传 .md 新建文章不同。未配置受信写回目标时，后台只读；绑定文件无法读取时，会显示 WordPress 已保存副本，该副本可能不是最新版。
请联系负责该文件来源的管理员或通过既有同步工具更新。普通上传不会创建这种绑定，也不会修改你电脑上的原文件。
公式排版失败时会保留 TeX 源码，请核对语法并重新预览。新建行内公式使用工具栏 数学（MathJax），TeX 输入框不需要外层美元符。
脚注引用和定义必须同名；缺失、重复、未使用的定义或定义内再次引用脚注会拒绝保存。命名、任务列表和原生数学转换边界见编辑与发布。
编辑桥预览用于检查转换后的正文；实际页面使用你的 WordPress 主题、页面布局和其他插件样式。保存后使用 WordPress 的预览或 查看文章 检查最终效果。若遇到登录失效或“无法验证此保存请求”，先保留未保存内容，重新登录并打开编辑器后重试。
上传插件 ZIP 不会安装私有 Node.js 环境。请管理员进入 设置 → MarkBridge 查看诊断，并按服务器配置准备与插件及 WordPress 匹配的私有目录。普通作者无法通过上传 Markdown 修复服务器配置。
WordPress 核心、转换内核或运行依赖与目录清单失配时会阻止写入。管理员应从同版本源码在新目录准备环境，完成沙箱诊断后切换；不要覆盖旧目录，也不要绕过隔离执行。详细要求与协调回退见服务器配置。
如果额外设置了内容安全策略（CSP），管理员检查 font-src 是否允许 data:；差异预览需要嵌入受信的本地数学字体。不要为此放宽 iframe 的脚本或同源权限。
先保留未保存内容，再提供插件与 WordPress 版本、操作入口、最短复现步骤、准确错误提示和去除私人内容的示例。不要发送密码、cookie、nonce 或未脱敏的私人文章。管理员可查看设置页诊断；配置细节仅对有 manage_options 权限的管理员显示。