# ueditorplus-dev

**Repository Path**: mo3408/ueditorplus-dev

## Basic Information

- **Project Name**: ueditorplus-dev
- **Description**: 基于 UEditorPlus做前端集成、配置、后端对接与源码级二次开发。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: skill

## README

# ueditorplus-dev

> UEditorPlus 富文本编辑器的**全链路开发技能** —— 从接进页面、配好工具条，到写后端接口、改源码加自己的按钮和插件。

[UEditorPlus](https://open.tecmz.com/ueditor-plus) 是 UEditor 的现代化重写版：UI 全部重做、换成矢量字体图标、砍掉过时插件、增强了上传与 AI 能力，API 保持兼容，可以无缝替换旧 UEditor。

**但官方只给了一份 PHP 假接口 demo（不落盘、直接返回示例图床 URL），正式环境的后端必须自己写。** 这个技能就是为了填上这段空白，把「查文档 → 猜实现 → 反复试错」压缩成一件事。

---

## 这个技能解决什么

| 痛点 | 本技能的做法 |
|---|---|
| 官方文档只讲「怎么配」，不讲「为什么这么配」 | 所有结论都回到源码和官方 demo 核对过 |
| **文档里的注释有 8 处与实际实现不符**，照抄必踩坑 | 逐条列出并给出正确值（见下方「文档陷阱更正」） |
| 后端接口没有规范说明，各语言各写各的 | 提炼出 10 个 action 的完整契约 + 可运行的多语言骨架生成器 |
| 二次开发改动不生效，不知道卡在哪一层 | 说清 `_src` → grunt → `dist` 的构建链路与常见断点 |
| 报错了只能从零排查 | 「症状 → 病因 → 章节」速查表，直接跳转 |

---

## 能做什么

- **前端集成** —— 原生 / Vue 2 / Vue 3 / React 四种接入方式，含完整可跑的代码。
- **配置调优** —— 工具条定制、上传限制、AI 功能、公式渲染、自动保存、动态隐藏按钮、只读模式。
- **后端对接** —— 10 个 action 的请求与返回规范：`config` / `image` / `crawl` / `snap` / `catch` / `video` / `audio` / `file` / `listImage` / `listFile`。
- **源码二次开发** —— 自定义工具栏按钮、下拉框、对话框、插件、图标字体、语言包，以及打包分发。
- **问题排查** —— 上传失败、图标不显示、`div` 被转成 `p`、后端配置不生效、改动没进 `dist` 等十几类实战症状。

---

## 目录结构

```
ueditorplus-dev/
├── SKILL.md                          # 主入口：方向判定 → 5 步工作流 → 10 条硬约束 → 症状速查
├── README.md                         # 本文件
├── references/
│   ├── 01-intro-integration.md       # 介绍、亮点、原生/Vue2/Vue3/React 集成
│   ├── 02-config.md                  # 配置项全量手册（12 类）+ 编辑器/事件/uNode API + 命令列表
│   ├── 03-backend.md                 # 后端接口契约 + PHP demo 逐段解读 + 安全清单 + 验收命令
│   ├── 04-secondary-dev.md           # 仓库结构、构建管线、自定义 UI 与插件、图标字体、语言包
│   └── 05-scenarios.md               # 官方 FAQ + 实战症状排查 + 最小复现环境 + 诊断顺序
└── scripts/
    ├── gen_backend.py                # 后端骨架生成器（php / python / node / go / java）
    └── check_backend_config.py       # action=config 返回体校验器
```

---

## 怎么用

### 方式一：作为技能自动触发

把本目录放到 `~/.workbuddy/skills/`（用户级）或项目的 `.workbuddy/skills/`（项目级）下即可。之后提到下列任一关键词会自动加载：

`UEditorPlus`、`UEditor Plus`、`ueditor-plus`、`魔众富文本编辑器`、`ueditor.config.js`、`serverUrl`、`toolbarShows`、`UE.registerUI`、`UE.plugin.register`、`vue-ueditor-wrap`、`react-ueditor-wrap`、`ueditor 二次开发 / 自定义按钮 / 自定义上传`。

### 方式二：直接读文档

按需求查表：

| 我想…… | 看哪份 |
|---|---|
| 把编辑器接进页面 / Vue / React | `references/01-intro-integration.md` |
| 改工具条、改上传限制、开 AI、开公式 | `references/02-config.md` |
| 写后端接口 | `references/03-backend.md` |
| 改源码、加按钮、加插件、打包 | `references/04-secondary-dev.md` |
| 出问题了，排查症状 | `references/05-scenarios.md` |

---

## 脚本用法

### 1. 生成后端骨架

```bash
# 基本用法：指定语言和目标目录
python scripts/gen_backend.py node -o ./server
python scripts/gen_backend.py python -o ./server --route /api/ueditor
python scripts/gen_backend.py php -o ./server --url-prefix https://cdn.example.com
```

| 参数 | 说明 |
|---|---|
| `<lang>` | 必填，`php` / `python` / `node` / `go` / `java` |
| `-o, --out` | 必填，输出目录 |
| `--route` | 接口路径前缀，默认 `/api/ueditor` |
| `--upload-dir` | 上传目录名，默认 `uploads` |
| `--url-prefix` | 返回 `url` 的前缀，如 CDN 域名 |
| `--max-image-mb` | 图片上限，默认 `10` |
| `--max-media-mb` | 视频/音频/附件上限，默认 `100` |
| `--no-jsonp` | 不生成 JSONP 分支（默认生成） |
| `--package` | Java 包名，默认 `com.example.ueditor` |
| `--force` | 覆盖已存在文件 |

生成物包含：`config` 动作、六类上传动作（含扩展名白名单、大小限制、按 `年/月` 分目录、`时间戳_随机串.扩展名` 命名）、`catch` 抓取远程图片（含 **SSRF 防护骨架**）、`listImage` / `listFile` 分页列表、CORS 与 `?callback=` JSONP 支持。

生成后按 `references/03-backend.md` 的契约逐条核对，再填业务逻辑（存盘策略、鉴权、CDN 前缀）。

### 2. 校验后端配置

```bash
# 校验本地 JSON 文件
python scripts/check_backend_config.py ./config.json

# 从标准输入读（例如 pipe 一个 curl 结果）
curl -s "https://example.com/api/ueditor?action=config" | python scripts/check_backend_config.py -

# 直连线上接口，并顺带探测图库与未知 action 的行为
python scripts/check_backend_config.py --url https://example.com/api/ueditor --probe
```

检查项包括：必需字段是否齐全、字段类型是否正确、动作名是否重复、`toolbarShow` 单复数误写、扩展名白名单格式、大小限制是否合理等。发现「错误 / 警告」两级问题，非零退出码可用于 CI。

---

## 文档陷阱更正

官方 `manual.html` / `backend.html` 的代码注释里有 **8 处**与当前源码/demo 不一致的旧值，已在本技能中逐条修正（详见 `references/02-config.md` §12）。照官方注释抄会直接踩坑：

| 配置项 / 接口 | 文档里写的 | 实际正确值 | 影响 |
|---|---|---|---|
| `imageFieldName` | 默认值 `upfile` | **`"file"`** | 后端按 `upfile` 取文件 → 永远收不到文件 |
| `scrawlActionName` | 默认值 `scrawl` | **`"crawl"`**（官方 PHP demo 里就是 `case 'crawl'`） | 涂鸦上传 404 |
| `toolbarShow` / `shortcutMenuShow` | 单数（manual 示例代码块） | **`toolbarShows` / `shortcutMenuShows`**（复数） | 后端下发的动态开关不生效 |
| `imageCompressBorder` | 默认值 `1600` | **`5000`** | 压缩过度 |
| `imageMaxSize` | 默认值 `2048000` | **`10485760`** | 允许大小算错 |
| `videoMaxSize` | 默认值 `102400000` | **`104857600`** | 同上 |
| `fileManagerActionName` | 注释写成「指定要列出文件的目录」 | 它是**动作名**，目录由后端决定 | 理解错接口 |
| `catch` 请求说明 | 「POST `source=url`」 | `source` 实际是**数组**（支持多图同时抓取，demo 里是 `foreach ($source as $imgUrl)`） | 只抓到第一张 / 类型报错 |

另外补了一条文档完全没提、但很关键的构建事实：

> **构建管线里没有 LESS 编译环节。** `themes/default/_css/` 下唯一的 `uibase.less` 不会被编译，改它不生效；图标字体以 base64 内联在 `uibase.css` 中。

---

## 验证状态

功能结论均在真实环境实机核对过，未验证的部分明确标注，不让人误信：

| 项目 | 状态 |
|---|---|
| Python 后端骨架 | **实机跑通** —— config / JSONP / 图片·涂鸦·视频上传 / 非法类型拒绝 / `listImage` 分页 / 未知 action 返回 400 / `catch` 拦截 `127.0.0.1` 与 `file://` |
| Node 后端骨架 | **实机跑通** —— 同上全部用例 |
| PHP / Go / Java 后端骨架 | 已生成并做语法检查，**未实机运行**（文档中已标注，并给出落地前自测命令） |
| 配置校验脚本 | **正反用例实测通过** —— 线上正常配置无告警，故意构造的错误配置逐条报出 |

---

## 资料来源

- 官方文档：<https://open.tecmz.com/ueditor-plus>（`guide` / `manual` / `upload-service` / `formula` / `backend` / `qa` / `change-log`）
- 在线演示：<https://open.tecmz.com/ueditor-plus/_examples/>
- 源码仓库：<https://gitee.com/modstart-lib/ueditor-plus> ｜ <https://github.com/modstart-lib/ueditor-plus>
- 参考版本：4.5.x ｜ 协议：Apache 2.0

文档与源码冲突时，**一律以源码和官方 demo 为准** —— 本技能的结论就是这么来的。