发布系统使用说明与改进计划

系统概述

本发布系统让你在本地用 Markdown 写文章和页面，一条命令直接发布到 WordPress，无需登录后台。

本地 Markdown  →  remark 解析  →  HTML  →  WordPress REST API  →  网站上线

核心文件：

文件 作用
publish.js 单文件发布/更新
batch_publish.js 批量发布（基于时间戳增量）
.env 存放 WordPress 站点地址和 API 凭据
.last-publish-time 记录上次发布时间，批量模式跳过未修改的文件

目录结构

publisher/
├── posts/                  # 文章目录
│   ├── 2024/
│   ├── 2025/
│   └── 2026/
├── pages/                  # 页面目录
│   └── about-me.md
├── publish.js              # 单文件发布脚本
├── batch_publish.js        # 批量发布脚本
├── set_feature_image.js    # 设置特色图片
├── .env                    # API 凭据（不入 git）
└── .last-publish-time      # 时间戳记录

自动识别规则：posts/ 下的文件 → 文章，pages/ 下的文件 → 页面。

Front Matter 字段

---
title: 文章标题           # 必填
slug: my-article-slug     # 必填，URL 标识（支持中文）
id: 123                   # 可选，已有文章 ID（用于更新）
categories: [WordPress]   # 可选，分类 slug 列表（必须已存在）
tags: [教程, 优化]        # 可选，标签 slug 列表（必须已存在）
featured_image: 456       # 可选，特色图片的媒体库 ID
parent: 0                 # 仅页面，父页面 ID
menu_order: 1             # 仅页面，菜单排序
---

⚠️ categories 和 tags 必须使用 WordPress 中已存在的分类/标签 slug。如果写了不存在的，发布会报错中断，不会自动创建。

发布命令

# 发布单篇文章
node publish.js posts/2026/my-article.md

# 发布单个页面
node publish.js pages/about.md

# 批量发布所有修改过的文件
node batch_publish.js

# 只发布文章或页面
node batch_publish.js --posts
node batch_publish.js --pages

# 预览模式（不实际发布）
node batch_publish.js --dry-run

# 强制全量发布
node batch_publish.js --all

# 调试模式
$env:DEBUG_PUBLISH="1"; node publish.js posts/xxx.md

工作流程

flowchart TD
    A[执行 node publish.js] --> B[解析 Front Matter]
    B --> C{slug 是否为空?}
    C -->|是| D[报错退出]
    C -->|否| E[Markdown → HTML]
    E --> F[检查分类/标签是否存在]
    F --> G{存在?}
    G -->|否| H[报错: 分类不存在]
    G -->|是| I{id 或 slug 匹配已有文章?}
    I -->|匹配| J[更新文章]
    I -->|不匹配| K[创建新文章]
    J --> L{front matter 有 id?}
    K --> M[自动写入 id 到 MD 文件]
    L -->|没有| M
    L -->|有| N[完成]
    M --> N

关键特性

自动 ID 回写：新文章发布成功后，系统自动把 WordPress 返回的文章 ID 写回 Markdown 文件的 front matter。下次修改这个文件时，系统通过 ID 精准更新，不会因 slug 变动而创建重复文章。

slug 保护：更新已有文章时，默认不修改 slug。即使你在 front matter 改了 slug，也只影响新文章，不会改已有文章的 URL。

Markdown 增强：

  • :::tip / :::warning / :::danger / :::info / :::note — Admonition 提示块
  • 【高亮文字】 — 内联高亮提示
  • GFM 表格、Emoji (:smile:) 完整支持
  • 外链自动 target="_blank"

存在的不足与改进方向

🔴 影响效率

  1. 不支持本地图片上传
    目前 featured_image 只能填 WordPress 媒体库中已存在的 ID。本地图片需要先手动上传到媒体库，再拿 ID。理想流程应该是：Markdown 里写 ![alt](local.png) → 解析时自动上传 → 替换为 CDN URL。

  2. 分类/标签报错信息不够友好
    目前报错 Term slug not found: categories:新分类，但没有列出已有的所有分类供参考。可以改进为：”分类「新分类」不存在，当前可用分类：WordPress, 性能优化, 生活随笔”。

  3. 批量发布遇错即停
    批量模式下一个文件失败，后续文件全部跳过。应该改为收集所有错误，最后汇总报告，不阻塞其他文件的发布。

🟡 缺少的高级功能

  1. 不支持定时发布
    front matter 没有 status: future + date 支持，无法设置定时发布。

  2. 不支持文章摘要
    没有 excerpt 字段，WordPress 只能自动截取前 55 字作为摘要，不可控。

  3. 不支持自定义字段
    无法通过 front matter 设置 WordPress 自定义字段（post meta）。

🟢 代码质量

  1. 存在未清理的测试代码
    addSignature() 函数和 remarkHighlightTipInline 插件标注为”测试用，可以删除”，但仍在代码中。

  2. addTargetBlank() 域名硬编码无效
    函数里判断 yourdomain.com 来决定是否为外链，实际上永远匹配不到，相当于所有链接都加了 target="_blank"。应该改为读取 .env 中的站点域名。

  3. .env 解析过于简单
    不支持引号内含空格的值，不支持行内注释，批量发布的 --posts --pages 与文件路径有命名歧义。

计划优先级

优先级 改进项 原因
P0 本地图片自动上传 目前图片工作流太繁琐
P1 错误汇总不中断 批量发布体验差
P1 友好报错（列出现有分类） 分类报错后不知道填什么
P2 文章摘要支持 影响 SEO 和搜索展示
P2 清理测试代码 代码整洁
P3 定时发布 锦上添花
P3 自定义字段 特殊需求
滚动至顶部