撰写文章

在部署完成并登录后台后，打开「文章管理」并点击「新建文章」即可进入文章编辑器。本节介绍文章正文、文章设置、附件、发布和保存等功能。

编辑器提供「富文本」「Markdown」「文章设置」和「附件管理」四个标签，四个标签共享同一篇文章内容，切换视图时不会生成两份正文。

文章编辑页面由 app/pages/admin/contents/edit.vue 提供，正文区域使用 app/components/MarkdownEditor.vue，工具栏使用 app/components/markdown-editor/EditorToolbar.vue，附件上传由文章附件接口处理。

编辑器

文章编辑器有富文本编辑器和 Markdown 编辑器两种。文章包含加粗、斜体、下划线、删除线、标题、引用、代码、代码块、无序列表、有序列表、链接、图片和表格等基本 Markdown 语法，同时具有折叠区块、提示框、视频、实况照片、链接卡片、轮播图、瀑布流图片、GitHub 或 Gitee 仓库卡片以及音乐播放器等扩展语法。

Markdown 模式以纯文本形式编辑文字，适合需要精确控制 Markdown 结构的场景。富文本模式和 Markdown 模式使用同一份内容，切换时会同步标题、段落、格式、表格、代码块和项目注册的自定义容器；在 Markdown 模式下，工具栏会把对应语法插入当前光标位置。

编辑器支持撤销与重做、查找和替换以及编辑器高度调整。富文本模式下可以使用 Ctrl 或 Command 加 K 插入链接，图片可以通过工具栏插入，也可以直接粘贴到编辑区并上传为文章附件；图片上传完成后，正文会自动写入附件地址。文章还没有保存时不能使用需要文章 ID 的粘贴上传功能。

完整富文本语法可前往 彻底换到新的 CMS 了，ImQi1 CMS 介绍 文章。

草稿云端同步

编辑器还会每 30 秒把正文静默同步到服务端，独立于「Ctrl+S 或停止输入 2 秒」触发的全量保存。即使关闭浏览器、切到其他设备，只要记得文章 ID，都能在下一次进入编辑页时拿到上次自动同步的内容，不会因浏览器缓存清理或设备更换丢稿。同步只动 content 与 update_time 两列，标题、分类、标签、封面、状态等元数据不会被覆盖。草稿期间元数据可能尚未填全，全量替换会反向把空值回写到服务端。

同步成功的最近时间会显示在保存按钮旁；网络异常或会话过期时同步静默失败并显示一行错误提示，不会打断编辑。登录会话过期（401 或 403）后未保存内容会被暂存到本地 localStorage，重新登录后由「自动保存」机制恢复并继续同步。CSRF token 在保存动作前需要刷新一次，同步走的是和保存同一条 token 通道。

点赞

文章详情页打开后，标题下方元信息区会出现一个心形点赞按钮，点击后做一次心形脉冲动画并迸发八颗 CSS 粒子；同一访客对同一篇文章只计一次，重复点击不会增加计数，已点过的心形保持红色激活态并切换 tooltip 为「已点赞过」。访客无需登录即可点赞，计数在首页、归档、分类、标签、搜索结果和文章详情页全量展示。

后端按「客户端 IP + User-Agent」取 SHA-256 摘要做访客指纹，配合文章 ID 组成唯一约束；前端用 localStorage 另存一份本地标记以防服务端按 IP 漂移导致状态丢失。点赞接口自带「单 IP 对每篇文章 5 分钟一次」的服务端限速，通用限流中间件再按 IP 维度对所有文章合计「每分钟 30 次」做兜底。

后台文章管理页（/admin/contents）的列表新增「点赞数」列，点击数值打开该文章的「点赞明细」弹窗（/admin/likes/[cid]），按时间倒序列出全部点赞记录，每行展示 IP、User-Agent 摘要、指纹前 8 位与点赞时间，每条可单条删除用于清理刷量。公开接口字段白名单与限速策略详见 Server 接口。

Markdown 语法

基本的 Markdown 语法不在此列出，这里仅介绍文章编辑器和前台正文渲染器额外支持的语法。

代码块

使用三个反引号包围代码，并在开头标注语言名称即可启用语法高亮。语言标识可以使用完整名称或常用缩写，例如 javascript、js、typescript、ts、python、py、java、c、cpp、css、html、json、bash、sh、sql、php、yaml、toml、markdown、vue、tsx、jsx、ini 和 powershell。未识别的语言仍会以普通等宽代码显示，不会影响正文发布。

Markdown```ts
const message = "Hello, ImQi1";
console.log(message);
```

语言后可以使用 + 补充文件名。文件名需要包含扩展名或路径分隔符，发布页会在代码块右上角显示文件名，并保留对应的语言高亮：

Markdown```ts+src/utils/date.ts
export function formatDate(value: Date) {
  return value.toISOString();
}
```

超过 14 行的代码块会默认折叠，点击展开按钮可以查看完整内容；发布页还提供复制代码按钮。代码行末尾可以使用 Shiki 标记显示增删或重点行，例如 // [!code ++]、// [!code --] 和 // [!code highlight]，注释符号应按所使用的语言调整。

实况照片

实况照片需要先在「附件管理」中通过实况照片入口上传 JPEG 文件。上传成功后，附件链接会带有 #live 标记；普通图片上传入口不会把普通 JPEG 自动识别为实况照片。

最直接的写法是在图片地址末尾保留 #live：

Markdown![旅行瞬间](/uploads/2026/09/example.jpg#live)

也可以使用实况照片容器，并在 URL 后面用空格写标题。容器的开头和结尾必须各占一行：

Markdown:::live-photo /uploads/2026/09/example.jpg#live 旅行瞬间
:::

如果使用容器时没有手动写 #live，前台会在渲染实况照片时自动补上该标记；为了便于复制和排查，建议始终保留上传接口返回的完整附件链接。图片替代文本中也可以加入 [live] 标记触发实况照片渲染，渲染后该标记不会显示在标题中。

附件选择对象存储时，若设置了上传后图片的后缀名（如 webp），则不能直接通过粘贴或普通附件上传功能上传实况照片，会失去后面的视频部分。应使用专用的“上传实况照片”按钮，它会绕过对象存储的图片处理策略，保留图片中的视频元素。

扩展语法

扩展语法统一使用 ::: 容器。开头写容器名称和参数，内容写在中间，最后用单独一行的 ::: 结束；容器必须与前后正文分隔开。富文本模式会把容器作为一个整体保留，Markdown 模式可以直接修改原始语法。

常用容器如下：

Markdown:::details 点击展开标题
折叠内容
:::

:::callout warning
这是一条警告提示。也可以使用 success、error 或 info。
:::

:::video https://example.com/video.mp4
:::

:::card https://example.com | 链接标题 | 链接描述 | https://example.com/cover.jpg
:::

:::simple-card https://example.com | 链接标题
:::

图片类容器使用一行一个资源，| 后面可以填写标题：

Markdown:::swiper
https://example.com/image1.jpg | 图片标题1
https://example.com/image2.jpg | 图片标题2
:::

:::waterfall
https://example.com/image1.jpg | 图片标题1
https://example.com/image2.jpg | 图片标题2
:::

仓库卡片支持 GitHub 和 Gitee：

Markdown:::repo https://github.com/username/repository
:::

音乐播放器支持自动识别链接、单曲和歌单三种形式。网易云、QQ 音乐、酷我和酷狗的标准 Markdown 链接会在服务端渲染时自动转换；也可以直接写容器：

Markdown:::music auto https://music.163.com/#/playlist?id=123456
:::

:::music song netease 123456
:::

:::music playlist netease 123456
:::

扩展容器的参数会按原文保存。若容器没有闭合，编辑器会将其当作普通 Markdown 文本处理，因此修改源码时要特别注意结尾的 :::。

文章设置

文章设置区域先填写基本信息。文章标题是必填项，文章描述用于 SEO 和分享，文章 Slug 用于生成文章地址，留空时会在保存后自动生成。首次保存后页面会转入该文章的编辑地址，后续可以继续修改并再次保存。

「封面设置」用于填写文章封面，开启「启用多封面」后可以设置多张封面并在文章页轮播显示。封面列表每行填写一张图片，图片地址后可以使用 || 补充封面标题：

Text/uploads/cover1.jpg || 文章封面1
/uploads/cover2.jpg || 文章封面2

「地图地点」用于把文章关联到旅行地图中的地点。文章首次保存前不能添加地点，保存后可以搜索已有地点并添加或移除关联；一个地点可以同时关联多篇文章。

「发布设置」可以在草稿和发布之间切换，草稿不会出现在前台；「发布日期」用于指定文章发表时间，「定时发布」用于指定一个未来的时间点，到点由内置定时任务（每分钟扫描一次）自动把状态切到「已发布」并失效前台缓存，「展示目录」用于控制文章详情页是否显示目录。开启目录后，文章页会根据正文中的 H2、H3 标题生成目录，桌面端显示在正文侧边，移动端不显示侧栏目录。定时发布只能对草稿生效，文章已是「已发布」时该控件隐藏；定时发布触发后字段会被清空，避免重复扫描。

附件管理

「文章附件」支持上传图片、视频和实况照片。普通附件支持 JPG、PNG、GIF、WebP、MP4 和 WebM，单个文件最大 10MB；实况照片使用专用入口上传 JPEG，单个文件最大 50MB。上传后的附件会显示预览、文件大小和图片尺寸，可以复制附件链接，也可以取消附件与文章的关联，再将复制的链接插入正文或 Markdown 中。

富文本编辑器和 Markdown 编辑器都支持直接粘贴图片。粘贴后的图片会自动上传为文章附件，正文会自动写入附件地址。

分类和标签

「分类设置」用于选择文章所属分类，至少需要选择一个分类才能保存；「标签设置」用于选择文章标签，标签是可选项，文章可以不关联任何标签。分类和标签都在对应设置卡片中勾选，文章保存时会一起提交。

填写内容后点击「保存文章」即可保存，保存按钮会显示当前保存状态。编辑器还会在停止输入后自动保存，页面显示「有未保存的更改」时表示当前内容尚未完成保存；登录会话过期时，未保存内容会暂存到本地，重新登录后可以继续保存。文章保存成功后可以点击「查看本文章」打开前台页面，草稿文章不能直接在前台预览。

分类和标签需要现在后台设置的对应面板添加，文章页面内只能选择已有的分类和标签。

普通文章

普通文章只需要选择一个普通分类即可，正文、封面、分类、标签、发布日期和目录设置都会按文章详情页的常规布局展示。文章可以没有封面，也可以设置单张或多张封面；是否使用多封面由「封面设置」中的开关决定。普通分类页会以文章卡片列出已发布文章，文章详情页则显示完整正文、封面、元信息、相关文章和评论区域。

图片文章

图片文章不使用单独的编辑器，仍然通过同一篇文章的标题、正文、封面、分类和标签进行维护。将文章关联到后台「图片分类 Slug」对应的分类后，前台会把它识别为图片分类文章；图片分类 Slug 在「系统设置」→「外观设置」中配置。

图片文章通常把图片地址填写在「封面列表」中，并根据需要开启多封面。图片分类页会将文章封面展开为瀑布流图片，首页的「最新图片」也会读取图片分类中的文章封面；文章详情页会根据图片分类切换对应的图片展示样式。文章正文仍然可以继续使用 Markdown、图片、实况照片、轮播图和其他编辑器组件。