kyle-editor 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -69
- package/dist/keditor.cjs +849 -217
- package/dist/keditor.es.js +849 -217
- package/dist/keditor.umd.js +849 -217
- package/package.json +3 -7
- package/types/index.d.ts +136 -4
- package/docs/api.md +0 -223
- package/docs/index.md +0 -8
- package/docs/integration.md +0 -296
- package/docs/npm-publish.md +0 -412
- package/docs/upload-adapter.md +0 -186
- package/src/core/commands.js +0 -311
- package/src/core/editor.js +0 -795
- package/src/core/format.js +0 -64
- package/src/core/history.js +0 -92
- package/src/core/icons.js +0 -49
- package/src/core/paste.js +0 -140
- package/src/core/sanitize.js +0 -182
- package/src/core/selection.js +0 -129
- package/src/core/toolbar.js +0 -465
- package/src/core/utils.js +0 -95
- package/src/index.js +0 -33
- package/src/media/media.js +0 -331
- package/src/ui/bubble.js +0 -270
- package/src/ui/popover.js +0 -507
- package/src/ui/preview.js +0 -59
- package/src/ui/source.js +0 -97
- package/src/ui/styles.js +0 -447
- package/src/ui/toast.js +0 -56
- package/src/upload/adapters.js +0 -206
- package/src/upload/chunk-uploader.js +0 -193
- package/src/upload/fingerprint.js +0 -38
- package/src/vue/index.js +0 -104
package/docs/npm-publish.md
DELETED
|
@@ -1,412 +0,0 @@
|
|
|
1
|
-
# 发布到 npm 并支持 `npm install`
|
|
2
|
-
|
|
3
|
-
本项目的产物已经按「可直接发布」的标准配置好,本文覆盖:包名选择 → 登录 → 本地验证 → 发布 → 版本管理 → 安装使用 → 私有源 / CI 自动发布。
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 0. 先决条件
|
|
8
|
-
|
|
9
|
-
| 项 | 要求 | 检查命令 |
|
|
10
|
-
|----|------|---------|
|
|
11
|
-
| npm CLI | ≥ 8(建议 ≥ 10) | `npm -v` |
|
|
12
|
-
| Node | ≥ 16 | `node -v` |
|
|
13
|
-
| npm 账号 | 已注册且邮箱已验证 | `npm whoami` |
|
|
14
|
-
| 包名 | **未被占用** | `npm view <包名> version` |
|
|
15
|
-
| 网络 | 能访问 `registry.npmjs.org` | `npm ping` |
|
|
16
|
-
|
|
17
|
-
未登录时先登录:
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
npm login # 新版 CLI 会打开浏览器授权
|
|
21
|
-
# 或 npm adduser --auth-type=legacy # 走用户名/密码/邮箱/OTP 的传统方式
|
|
22
|
-
npm whoami # 确认已登录
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
账号开启了 2FA 的,发布时会要求输入一次性验证码(OTP):
|
|
26
|
-
|
|
27
|
-
```bash
|
|
28
|
-
npm publish --access public --otp=123456
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
---
|
|
32
|
-
|
|
33
|
-
## 1. 包名:已定为 `kyle-editor`
|
|
34
|
-
|
|
35
|
-
`keditor` 在 npm 上已被他人注册,无法使用:
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
npm view keditor version
|
|
39
|
-
# 0.0.1 ← 已占用
|
|
40
|
-
npm view kyle-editor version
|
|
41
|
-
# 404 Not Found ← 可用,本项目采用的名字
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
> 无作用域的名字遵循「先到先得」,`kyle-editor` 目前可用但没有保留机制 —— 确定后尽快发布占位。
|
|
45
|
-
> 若希望长期独占、不怕重名,可改用作用域包 `@kyle/kyle-editor`(作用域 = npm 用户名或组织名,别人无法抢占,发布必须带 `--access public`)。
|
|
46
|
-
|
|
47
|
-
### 名字已经同步到这些地方(无需再改)
|
|
48
|
-
|
|
49
|
-
| 位置 | 内容 |
|
|
50
|
-
|------|------|
|
|
51
|
-
| `package.json` | `name: "kyle-editor"` |
|
|
52
|
-
| `src/vue/index.js` | `import { KEditor, defaults } from 'kyle-editor'` |
|
|
53
|
-
| `vite.config.vue.js` | `external: ['vue', 'kyle-editor']`、`globals: { 'kyle-editor': 'KEditor' }` |
|
|
54
|
-
| `README.md` / `docs/*.md` / `types/*.d.ts` / `demo/esm.html` | 所有 `npm install kyle-editor`、`from 'kyle-editor'`、`kyle-editor/vue` |
|
|
55
|
-
|
|
56
|
-
> ⚠️ **`external` 与包名必须一致**:Vue 产物把核心包作为外部依赖打包,`dist/keditor-vue.*.js` 里会留下裸说明符 `from "kyle-editor"`。若二者不一致,用户 `npm install` 后会报 `Cannot find module`。`npm run test:package` 会强制校验这一点。
|
|
57
|
-
|
|
58
|
-
### 不需要改的东西
|
|
59
|
-
|
|
60
|
-
`dist/` 下的**文件名**(`keditor.es.js` / `keditor.umd.js` / `keditor-vue.es.js`)和**全局变量名**(`window.KEditor`、`window.KEditorVue`)与包名无关,保持不变 —— 改它们会连带影响 `<script>` 引入方式和 CDN 路径。
|
|
61
|
-
|
|
62
|
-
以后若要再改名,同步这 4 处即可:`package.json.name`、`src/vue/index.js` 的 import、`vite.config.vue.js` 的 `external`/`globals`、文档里的包说明符(`dist` 文件名与 `KEditor` 全局名不动)。
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
## 2. package.json 中与发布相关的字段(已配置)
|
|
67
|
-
|
|
68
|
-
```jsonc
|
|
69
|
-
{
|
|
70
|
-
"name": "…",
|
|
71
|
-
"version": "1.0.0",
|
|
72
|
-
"type": "module",
|
|
73
|
-
|
|
74
|
-
// 三种模块格式的入口,兼容 ESM / CJS / 浏览器
|
|
75
|
-
"main": "./dist/keditor.cjs", // require()
|
|
76
|
-
"module": "./dist/keditor.es.js", // 打包器优先
|
|
77
|
-
"unpkg": "./dist/keditor.umd.js", // <script src="https://unpkg.com/…">
|
|
78
|
-
"jsdelivr":"./dist/keditor.umd.js",
|
|
79
|
-
"types": "./types/index.d.ts",
|
|
80
|
-
|
|
81
|
-
// 子路径导出:keditor 与 keditor/vue 分别解析
|
|
82
|
-
"exports": {
|
|
83
|
-
".": { "types": "./types/index.d.ts", "import": "./dist/keditor.es.js", "require": "./dist/keditor.cjs" },
|
|
84
|
-
"./vue": { "types": "./types/vue.d.ts", "import": "./dist/keditor-vue.es.js", "require": "./dist/keditor-vue.cjs" },
|
|
85
|
-
"./package.json": "./package.json"
|
|
86
|
-
},
|
|
87
|
-
|
|
88
|
-
// 白名单:只有这些会进 tarball(node_modules / demo / test 自动排除)
|
|
89
|
-
"files": ["dist", "src", "types", "docs", "README.md", "LICENSE"],
|
|
90
|
-
|
|
91
|
-
// 样式随 JS 运行时注入,禁止 tree-shaking 误删 → 必须为 true
|
|
92
|
-
"sideEffects": true,
|
|
93
|
-
|
|
94
|
-
"license": "MIT",
|
|
95
|
-
"engines": { "node": ">=16" },
|
|
96
|
-
|
|
97
|
-
// Vue 为可选 peer:只用 <script>/核心 API 的项目不会被强制装 Vue
|
|
98
|
-
"peerDependencies": { "vue": "^3.0.0" },
|
|
99
|
-
"peerDependenciesMeta": { "vue": { "optional": true } },
|
|
100
|
-
|
|
101
|
-
"publishConfig": { "access": "public" }
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
建议再补上(发布前填写真实地址,缺失不影响功能但影响 npm 页面展示):
|
|
106
|
-
|
|
107
|
-
```jsonc
|
|
108
|
-
{
|
|
109
|
-
"repository": { "type": "git", "url": "git+https://github.com/<你>/keditor.git" },
|
|
110
|
-
"homepage": "https://github.com/<你>/keditor#readme",
|
|
111
|
-
"bugs": { "url": "https://github.com/<你>/keditor/issues" },
|
|
112
|
-
"author": "kyle <zhendong.li@edoctor.cn>"
|
|
113
|
-
}
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
> ⚠️ **`main`/`exports.require` 必须指向 `.cjs` 文件**。因为本包 `type` 是 `module`,Node 会用最近的 `package.json` 判定 `.js` 为 ESM;若 CJS 产物叫 `xxx.cjs.js`,`require()` 会把它当 ESM 加载,**导出全部丢失得到空对象**。`npm run test:package` 已把这条列入强制校验。
|
|
117
|
-
|
|
118
|
-
`scripts` 里已经准备好:
|
|
119
|
-
|
|
120
|
-
| 命令 | 作用 |
|
|
121
|
-
|------|------|
|
|
122
|
-
| `npm run build` | 产出 `dist/` 6 个文件 |
|
|
123
|
-
| `npm run verify` | build + 66 项冒烟测试 + 4 个 demo 页健康检查 + 类型校验 |
|
|
124
|
-
| `npm run test:package` | 校验包名/exports 路径/`.cjs` 后缀/裸说明符一致性(63 项) |
|
|
125
|
-
| `npm run test:install` | **打 tarball → 隔离目录全新安装 → headless Chrome 跑 40 项消费者用例**(UMD/ESM/Vue 三条集成路径) |
|
|
126
|
-
| `npm run pack:check` | build + 一致性校验,并打印**将要发布的文件清单与体积**(不发布) |
|
|
127
|
-
| `npm run release` | 自动先跑 `prerelease`(=verify + test:install) 再 `npm publish` |
|
|
128
|
-
| `npm run release:beta` | 发到 `beta` 标签,不影响 `latest` |
|
|
129
|
-
|
|
130
|
-
> `publishConfig` 已写死 `registry: https://registry.npmjs.org`。即使本地 `npm config get registry` 指向
|
|
131
|
-
> npmmirror 等**只读镜像**,`npm run release` 也会发到官方源,不会误报 403。
|
|
132
|
-
|
|
133
|
-
---
|
|
134
|
-
|
|
135
|
-
## 3. 发布前本地验证(强烈建议)
|
|
136
|
-
|
|
137
|
-
### 3.1 看将要发布的内容
|
|
138
|
-
|
|
139
|
-
```bash
|
|
140
|
-
npm run pack:check
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
关注输出末尾:`total files`、`package size`、`unpacked size`,以及**是否混入了不该发的文件**(`.DS_Store`、`test/`、`demo/`、`.idea/`)。
|
|
144
|
-
|
|
145
|
-
### 3.2 真实打 tarball 并在干净目录安装(已自动化)
|
|
146
|
-
|
|
147
|
-
这是最接近用户实际体验的验证,**一条命令跑完**:
|
|
148
|
-
|
|
149
|
-
```bash
|
|
150
|
-
npm run build && npm run test:install
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
它会自动完成:`npm pack` → 在 `.pack-verify/install` 建**带独立 `package.json`** 的隔离目录 →
|
|
154
|
-
`npm install <tarball> vue@3`(走官方源)→ 起临时静态服务 → headless Chrome 打开
|
|
155
|
-
`test/fixtures/consumer.html` 跑 **40 项断言**,覆盖:
|
|
156
|
-
|
|
157
|
-
- **UMD `<script>` 路径**:全局 `KEditor`、工具栏渲染、CSS 随 JS 注入、`setContent/getHTML/getText/getJSON/counts`
|
|
158
|
-
- **安全**:`sanitize` 剔除 `onclick` / `onerror`
|
|
159
|
-
- **源码与预览**:`enterSource` / `exitSource` / `toggleSource` / `openPreview` / `closePreview`
|
|
160
|
-
- **网络链接插入**:`insertImage(url)` / `insertVideo(url)`,并校验 `counts` 的媒体计数
|
|
161
|
-
- **ESM 路径**:动态 `import()` 安装后的 `dist/keditor.es.js`,默认+具名导出完整,`destroy` 清理
|
|
162
|
-
- **Vue 3 路径**:`app.use(default)` 注册全局 `<k-editor>`、默认导出直接当组件、`v-model` 双向绑定(含外部赋值回写)、`ref` 暴露 `editor/getHTML/setContent`、`unmount` 卸载
|
|
163
|
-
|
|
164
|
-
任一断言失败则退出码非 0,`npm run release` 会被 `prerelease` 拦下。
|
|
165
|
-
加 `--keep` 可保留安装目录人工复查:`node test/check-install.mjs --keep`。
|
|
166
|
-
|
|
167
|
-
<details>
|
|
168
|
-
<summary>手动版(不跑浏览器,只验四个入口能解析)</summary>
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
npm run build
|
|
172
|
-
npm pack # 生成 kyle-editor-1.0.0.tgz
|
|
173
|
-
|
|
174
|
-
mkdir -p .pack-verify/manual && cd .pack-verify/manual
|
|
175
|
-
cat > package.json <<'JSON'
|
|
176
|
-
{ "name": "pack-verify", "private": true, "version": "1.0.0" }
|
|
177
|
-
JSON
|
|
178
|
-
npm install ../../kyle-editor-1.0.0.tgz
|
|
179
|
-
|
|
180
|
-
node -e "const m=require('kyle-editor');console.log('CJS 核心:',Object.keys(m).length,'个导出, create=',typeof m.create)"
|
|
181
|
-
node -e "const m=require('kyle-editor/vue');console.log('CJS Vue :',Object.keys(m).join(','))"
|
|
182
|
-
node --input-type=module -e "const m=await import('kyle-editor');console.log('ESM 核心:',Object.keys(m).length,'个导出, default=',typeof m.default)"
|
|
183
|
-
node --input-type=module -e "const m=await import('kyle-editor/vue');console.log('ESM Vue :',Object.keys(m).join(','))"
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
期望输出(已实测):
|
|
187
|
-
|
|
188
|
-
```
|
|
189
|
-
CJS 核心: 22 个导出, create= function
|
|
190
|
-
CJS Vue : KEditor,KEditorPlugin,KEditorVue,default,useKEditor
|
|
191
|
-
ESM 核心: 22 个导出, default= function
|
|
192
|
-
ESM Vue : KEditor,KEditorPlugin,KEditorVue,default,useKEditor
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
</details>
|
|
196
|
-
|
|
197
|
-
> ⚠️ 临时验证目录**必须有自己的 `package.json`**。否则 npm 会向上找到项目根的 `package.json`,把 tarball 装进本项目自己(并往 `dependencies` 里写入 `"kyle-editor": "file:...tgz"` 的自依赖)。万一发生了:删掉 `package.json` 里的 `dependencies` 字段、`rm -rf node_modules/kyle-editor`,再跑 `npm install --package-lock-only` 重建 lock。`test/check-install.mjs` 已自动处理这一点。
|
|
198
|
-
|
|
199
|
-
---
|
|
200
|
-
|
|
201
|
-
## 4. 正式发布
|
|
202
|
-
|
|
203
|
-
```bash
|
|
204
|
-
# 首次发布(1.0.0)
|
|
205
|
-
npm run release
|
|
206
|
-
# 等价于:npm run verify && npm publish --access public
|
|
207
|
-
|
|
208
|
-
# 若账号开了 2FA
|
|
209
|
-
npm publish --access public --otp=123456
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
成功后:
|
|
213
|
-
|
|
214
|
-
- 包页面:`https://www.npmjs.com/package/<包名>`(作用域包为 `/package/@scope/name`)
|
|
215
|
-
- CDN 自动可用(发布后约 1–2 分钟生效):
|
|
216
|
-
- `https://unpkg.com/<包名>/dist/keditor.umd.js`
|
|
217
|
-
- `https://cdn.jsdelivr.net/npm/<包名>/dist/keditor.umd.js`
|
|
218
|
-
|
|
219
|
-
### 4.1 先发 beta 试水
|
|
220
|
-
|
|
221
|
-
```bash
|
|
222
|
-
npm version 1.0.1-beta.0 --no-git-tag-version
|
|
223
|
-
npm run release:beta
|
|
224
|
-
npm install <包名>@beta # 用户侧
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
`beta` 标签不会成为 `latest`,普通 `npm install <包名>` 不受影响。
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
## 5. 版本管理与后续更新
|
|
232
|
-
|
|
233
|
-
遵循语义化版本 `主.次.补丁`:
|
|
234
|
-
|
|
235
|
-
```bash
|
|
236
|
-
npm version patch # 1.0.0 → 1.0.1 修 bug
|
|
237
|
-
npm version minor # 1.0.0 → 1.1.0 加功能,向下兼容
|
|
238
|
-
npm version major # 1.0.0 → 2.0.0 破坏性变更
|
|
239
|
-
npm publish --access public
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
`npm version` 会自动改 `package.json`、生成 `package-lock.json` 变更并打 git tag(在非 git 仓库中会跳过 tag,可加 `--no-git-tag-version`)。
|
|
243
|
-
|
|
244
|
-
发布后校验:
|
|
245
|
-
|
|
246
|
-
```bash
|
|
247
|
-
npm view <包名> versions --json # 历史版本
|
|
248
|
-
npm view <包名> dist-tags # latest / beta 指向
|
|
249
|
-
npm cache clean --force && npm install <包名>@1.0.1 # 全新拉一次
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
### 5.1 撤包 / 废弃
|
|
253
|
-
|
|
254
|
-
```bash
|
|
255
|
-
npm deprecate <包名>@1.0.0 "有严重问题,请升级到 1.0.1" # 推荐:安装时给出警告
|
|
256
|
-
npm unpublish <包名>@1.0.0 # 仅发布 72 小时内、且无其他包依赖时允许
|
|
257
|
-
npm unpublish <包名> --force # 整包撤销(需邮箱验证,慎用)
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
> 已发布的版本号**不可复用**,即使撤包也不能再发同一个号,只能往上加版本。
|
|
261
|
-
|
|
262
|
-
---
|
|
263
|
-
|
|
264
|
-
## 6. 用户安装与集成
|
|
265
|
-
|
|
266
|
-
发布成功后,使用方只需:
|
|
267
|
-
|
|
268
|
-
```bash
|
|
269
|
-
npm install kyle-editor # 换成你的实际包名
|
|
270
|
-
# 用 Vue 组件的项目
|
|
271
|
-
npm install kyle-editor vue@^3
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
### 6.1 打包器 / ESM
|
|
275
|
-
|
|
276
|
-
```js
|
|
277
|
-
import KEditor from 'kyle-editor'
|
|
278
|
-
import { createApp } from 'vue'
|
|
279
|
-
import KEditorVue, { KEditorComponent } from 'keditor/vue'
|
|
280
|
-
|
|
281
|
-
createApp(App).use(KEditorVue).mount('#app')
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
样式无需单独引入 —— CSS 随 JS 在运行时注入。
|
|
285
|
-
|
|
286
|
-
### 6.2 零构建(`<script>` / CDN)
|
|
287
|
-
|
|
288
|
-
```html
|
|
289
|
-
<script src="https://unpkg.com/keditor/dist/keditor.umd.js"></script>
|
|
290
|
-
<script>
|
|
291
|
-
const editor = KEditor.create('#editor', { height: 460 })
|
|
292
|
-
</script>
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
Vue 3 的 UMD 版本对应 `dist/keditor-vue.umd.js`(需先引入 `vue.global.prod.js`)。
|
|
296
|
-
|
|
297
|
-
完整的 API、上传适配器接入方式见 `docs/api.md` 与 `docs/upload-adapter.md`。
|
|
298
|
-
|
|
299
|
-
---
|
|
300
|
-
|
|
301
|
-
## 7. 发布到私有 npm 源
|
|
302
|
-
|
|
303
|
-
公司内网发布(不占用公网包名,可直接叫 `keditor`):
|
|
304
|
-
|
|
305
|
-
```jsonc
|
|
306
|
-
// package.json
|
|
307
|
-
{ "publishConfig": { "registry": "https://npm.your-company.com/", "access": "public" } }
|
|
308
|
-
```
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
npm login --registry=https://npm.your-company.com/
|
|
312
|
-
npm publish
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
用户侧配置:
|
|
316
|
-
|
|
317
|
-
```ini
|
|
318
|
-
# 项目根目录 .npmrc
|
|
319
|
-
registry=https://npm.your-company.com/
|
|
320
|
-
# 或只对某个作用域走私服
|
|
321
|
-
@your-org:registry=https://npm.your-company.com/
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
---
|
|
325
|
-
|
|
326
|
-
## 8. CI 自动发布(GitHub Actions 示例)
|
|
327
|
-
|
|
328
|
-
```yaml
|
|
329
|
-
# .github/workflows/publish.yml
|
|
330
|
-
name: publish
|
|
331
|
-
on:
|
|
332
|
-
push:
|
|
333
|
-
tags: ['v*'] # 打 tag 才发布
|
|
334
|
-
|
|
335
|
-
jobs:
|
|
336
|
-
publish:
|
|
337
|
-
runs-on: ubuntu-latest
|
|
338
|
-
permissions:
|
|
339
|
-
contents: read
|
|
340
|
-
id-token: write # npm provenance 需要
|
|
341
|
-
steps:
|
|
342
|
-
- uses: actions/checkout@v4
|
|
343
|
-
- uses: actions/setup-node@v4
|
|
344
|
-
with:
|
|
345
|
-
node-version: 20
|
|
346
|
-
registry-url: https://registry.npmjs.org
|
|
347
|
-
- run: npm ci
|
|
348
|
-
- run: npm run verify
|
|
349
|
-
- run: npm run test:install # 打 tarball 真实安装 + headless Chrome 跑 40 项消费者用例
|
|
350
|
-
- run: npm publish --access public --provenance
|
|
351
|
-
env:
|
|
352
|
-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
`NPM_TOKEN` 在 npmjs.com → Access Tokens 生成 **Granular Access Token**(勾选该包、权限 `Read and write`),存到仓库 Secrets。加 `--provenance` 可在包页面显示构建来源徽章,提升可信度。
|
|
356
|
-
|
|
357
|
-
---
|
|
358
|
-
|
|
359
|
-
## 9. 常见问题
|
|
360
|
-
|
|
361
|
-
| 现象 | 原因 / 处理 |
|
|
362
|
-
|------|------------|
|
|
363
|
-
| `ENEEDAUTH need auth` | 未登录 → `npm login` |
|
|
364
|
-
| `403 Forbidden - You do not have permission to publish "keditor"` | 包名被占用 → 换名或用作用域 |
|
|
365
|
-
| `402 Payment Required` | 作用域包默认私有 → 加 `--access public` |
|
|
366
|
-
| `EPUBLISHCONFLICT` / `cannot publish over previously published version` | 版本号重复 → `npm version patch` 后重发 |
|
|
367
|
-
| `E403 forbidden` + 提到 two-factor | 账号强制 2FA → `--otp=123456`,或把 token 权限设为 Automation |
|
|
368
|
-
| 装上了但 `Cannot find module 'kyle-editor/vue'` | `exports` 子路径写错或 `dist` 没进 `files` → `npm run pack:check` 核对 |
|
|
369
|
-
| 安装后样式丢失 | `sideEffects` 被设成 `false` 导致注入代码被摇掉 → 保持 `true` |
|
|
370
|
-
| `EBADENGINE` 警告 | 用户 Node 低于 `engines.node` → 调低或让用户升级 Node |
|
|
371
|
-
| CDN 拿不到最新文件 | unpkg/jsdelivr 有缓存 → `https://unpkg.com/kyle-editor@1.0.1/dist/keditor.umd.js` 锁定版本 |
|
|
372
|
-
| `require('kyle-editor')` 得到空对象 `{}` | `type: module` 的包里 CJS 产物用了 `.js` 后缀,Node 按最近 package.json 当成 ESM 解析 → CJS 产物必须是 `.cjs`(本项目已修,`npm run test:package` 会校验) |
|
|
373
|
-
| 服务端渲染报 `document is not defined` | 编辑器只能在浏览器运行 → Next.js 用 `'use client'` + `dynamic(..., { ssr: false })`,Nuxt 用 `.client` 插件 + `<ClientOnly>`,详见 `docs/integration.md` §3.5 |
|
|
374
|
-
| Vue 里用了组件但渲染出**空白且无任何报错** | 把默认导出当成普通对象传给 `h()` 时会渲染成 `<!---->`。本包的默认导出是**自带 `install` 的组件**,`app.use(KEditorVue)` 与 `<KEditorVue />` 两种写法都可用;若仍异常,改用显式具名导出 `import { KEditorVue } from 'kyle-editor/vue'`。`npm run test:install` 会回归这两种写法 |
|
|
375
|
-
| 发到公司源失败 | 检查 `.npmrc` registry 与该源的登录态(`npm whoami --registry=…`) |
|
|
376
|
-
|
|
377
|
-
---
|
|
378
|
-
|
|
379
|
-
## 10. 一键发布检查清单
|
|
380
|
-
|
|
381
|
-
本项目已完成全部发布准备(包名、exports、`.cjs` 后缀、LICENSE、验证脚本均已就绪),你只需跑这 3 条:
|
|
382
|
-
|
|
383
|
-
```bash
|
|
384
|
-
cd /Users/kyle/Desktop/work/kyle/keditor
|
|
385
|
-
|
|
386
|
-
npm login # 1) 登录(会拉起浏览器授权;开了 2FA 则发布时补 --otp)
|
|
387
|
-
npm view kyle-editor version # 2) 应返回 404,确认名字仍可用
|
|
388
|
-
npm run release # 3) 构建 + 66 项冒烟 + 4 页健康检查 + 类型/包配置校验
|
|
389
|
-
# + 40 项真实安装浏览器验证,全部通过后才 publish
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
> `npm login` 必须由**你本人**完成(浏览器授权 / 2FA),无法代执行。
|
|
393
|
-
> 若本地默认源是 npmmirror 等镜像也无需改动:`publishConfig.registry` 已写死官方源。
|
|
394
|
-
|
|
395
|
-
发布后确认:
|
|
396
|
-
|
|
397
|
-
```bash
|
|
398
|
-
npm whoami # 当前登录账号
|
|
399
|
-
npm view kyle-editor versions --json # 已上线版本
|
|
400
|
-
npm view kyle-editor dist-tags # latest 指向 1.0.0
|
|
401
|
-
open https://www.npmjs.com/package/kyle-editor
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
完整验证清单(可选):
|
|
405
|
-
|
|
406
|
-
| 步骤 | 命令 | 期望 |
|
|
407
|
-
|------|------|------|
|
|
408
|
-
| 构建 + 全量验证 | `npm run verify` | 66/66 冒烟、4 页健康、类型通过、63 项包配置通过 |
|
|
409
|
-
| 核对发布内容 | `npm run pack:check` | 38 个文件,约 200 KB,无 test/demo/.DS_Store |
|
|
410
|
-
| **真实安装 + 浏览器验证** | `npm run test:install` | 40/40 通过(UMD/ESM/Vue 三条集成路径) |
|
|
411
|
-
| 正式发布 | `npm run release` | 返回包页面 URL |
|
|
412
|
-
| 先发 beta 试水 | `npm run release:beta` | `dist-tags` 出现 beta,latest 不变 |
|
package/docs/upload-adapter.md
DELETED
|
@@ -1,186 +0,0 @@
|
|
|
1
|
-
# 分片上传(Chunk Upload)
|
|
2
|
-
|
|
3
|
-
编辑器的图片与视频统一走 `ChunkUploader`:**切片 → 并发上传 → 失败重试 → 合并**。它只依赖一个适配器对象,因此既能在**无后端**环境下演示,也能一行切换成真实服务。
|
|
4
|
-
|
|
5
|
-
```
|
|
6
|
-
File
|
|
7
|
-
└─ 切片(file.slice,默认 1MB/片)
|
|
8
|
-
├─ worker 1 → put(chunk 0) → put(chunk 3) … ← 并发数 concurrency
|
|
9
|
-
├─ worker 2 → put(chunk 1) …
|
|
10
|
-
└─ worker 3 → put(chunk 2) …
|
|
11
|
-
每片失败自动重试 retries 次(退避 600ms * n)
|
|
12
|
-
└─ 全部完成 → complete() → 返回最终 url → 替换编辑器内的占位块
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
进度、已传字节、分片数、实时速度会通过 `onProgress(ratio, info)` 回传给编辑区占位块。
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## 1. 三种开箱适配器
|
|
20
|
-
|
|
21
|
-
### 1.1 mock(默认,无需后端)
|
|
22
|
-
|
|
23
|
-
```js
|
|
24
|
-
KEditor.create('#editor', { uploader: 'mock' })
|
|
25
|
-
|
|
26
|
-
// 可调参数
|
|
27
|
-
KEditor.create('#editor', {
|
|
28
|
-
uploader: KEditor.mockAdapter({
|
|
29
|
-
speed: 8, // 模拟带宽 MB/s
|
|
30
|
-
latency: 160, // 每片固定往返 ms
|
|
31
|
-
failFirstChunk: true,// 演示「分片失败 → 自动重试」
|
|
32
|
-
onEvent: (type, payload) => console.log(type, payload), // init/chunk/complete/instant/abort
|
|
33
|
-
}),
|
|
34
|
-
upload: { chunkSize: 256 * 1024 },
|
|
35
|
-
})
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
特点:分片真实切片与限速;完成后用 `URL.createObjectURL` 生成本地地址,可直接预览;同一文件重复上传命中「秒传」,不再重复切片。
|
|
39
|
-
|
|
40
|
-
### 1.2 http(对接真实后端)
|
|
41
|
-
|
|
42
|
-
```js
|
|
43
|
-
KEditor.create('#editor', {
|
|
44
|
-
uploader: {
|
|
45
|
-
type: 'http',
|
|
46
|
-
initUrl: '/api/upload/init',
|
|
47
|
-
chunkUrl: '/api/upload/chunk',
|
|
48
|
-
completeUrl: '/api/upload/complete',
|
|
49
|
-
abortUrl: '/api/upload/abort', // 可选
|
|
50
|
-
mode: 'raw', // 'raw' 裸 body(推荐)| 'formdata'
|
|
51
|
-
headers: () => ({ Authorization: `Bearer ${getToken()}` }),
|
|
52
|
-
withCredentials: true, // 需要 Cookie 时
|
|
53
|
-
parse: (json) => json.data, // 统一响应外层包装
|
|
54
|
-
},
|
|
55
|
-
upload: { chunkSize: 5 * 1024 * 1024, concurrency: 4, retries: 2, fingerprint: 'strong' },
|
|
56
|
-
})
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
### 1.3 simple(已有单次上传接口)
|
|
60
|
-
|
|
61
|
-
```js
|
|
62
|
-
KEditor.create('#editor', {
|
|
63
|
-
uploader: KEditor.simpleAdapter(async (file, { signal, onProgress }) => {
|
|
64
|
-
const form = new FormData()
|
|
65
|
-
form.append('file', file)
|
|
66
|
-
const res = await fetch('/api/upload', { method: 'POST', body: form, signal })
|
|
67
|
-
onProgress?.(file.size, file.size)
|
|
68
|
-
return (await res.json()).url // 也可直接返回字符串
|
|
69
|
-
}),
|
|
70
|
-
})
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
---
|
|
74
|
-
|
|
75
|
-
## 2. 后端接口约定(推荐实现)
|
|
76
|
-
|
|
77
|
-
### `POST /api/upload/init`
|
|
78
|
-
|
|
79
|
-
请求:
|
|
80
|
-
|
|
81
|
-
```json
|
|
82
|
-
{ "fileName": "a.mp4", "fileSize": 73400320, "fileType": "video/mp4",
|
|
83
|
-
"lastModified": 1758000000000, "identifier": "…", "chunkSize": 1048576, "totalChunks": 71 }
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
响应(三选一):
|
|
87
|
-
|
|
88
|
-
```jsonc
|
|
89
|
-
{ "uploadId": "u_8f3c", "uploadedChunks": [0, 1, 2] } // 断点续传:告知已存在哪些片
|
|
90
|
-
{ "url": "https://cdn/x.png", "key": "…" } // 秒传:identifier 已存在,直接返回地址
|
|
91
|
-
{ "uploadId": "u_8f3c", "uploadedChunks": [] } // 全新任务
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
### `PUT /api/upload/chunk?uploadId=u_8f3c&index=3&total=71&filename=a.mp4`
|
|
95
|
-
|
|
96
|
-
- `mode: 'raw'`:请求体是二进制分片,`Content-Type: application/octet-stream`,服务端按 `uploadId` 落盘为 `parts/{index}`,可用 `X-Chunk-Index` 头做幂等校验。
|
|
97
|
-
- `mode: 'formdata'`:`multipart/form-data`,文件字段名 `fieldName`(默认 `file`),附带 `uploadId` / `index` / `total` / `filename`。
|
|
98
|
-
- 响应:`{}` 即可;若返回 `{ "url": "…" }` 则该分片自带地址(适合对象存储分片直传)。
|
|
99
|
-
|
|
100
|
-
### `POST /api/upload/complete`
|
|
101
|
-
|
|
102
|
-
```json
|
|
103
|
-
{ "uploadId": "u_8f3c", "identifier": "…", "fileName": "a.mp4", "fileSize": 73400320,
|
|
104
|
-
"fileType": "video/mp4", "chunkSize": 1048576, "totalChunks": 71 }
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
响应必须包含 `url`:
|
|
108
|
-
|
|
109
|
-
```json
|
|
110
|
-
{ "url": "https://cdn/a.mp4", "key": "media/2026/09/a.mp4", "poster": "https://cdn/a.jpg", "duration": 63 }
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### `POST /api/upload/abort`
|
|
114
|
-
|
|
115
|
-
`{ "uploadId": "u_8f3c" }`,用于清理临时分片(用户取消时触发,失败会被忽略)。
|
|
116
|
-
|
|
117
|
-
> Node/Express 的极简实现思路:`init` 建目录 + 扫已存在分片返回 `uploadedChunks`;`chunk` 用 `raw body → fs.createWriteStream`;`complete` 按 index 顺序 `concat` 后交给对象存储。若直接用 OSS/S3 分片上传,把 `put` 换成「拿签名 URL → PUT」即可,`complete` 调用 `CompleteMultipartUpload`。
|
|
118
|
-
|
|
119
|
-
---
|
|
120
|
-
|
|
121
|
-
## 3. 自定义适配器
|
|
122
|
-
|
|
123
|
-
只要实现 `put`,其余可选:
|
|
124
|
-
|
|
125
|
-
```js
|
|
126
|
-
const adapter = {
|
|
127
|
-
async init(meta, { signal }) {
|
|
128
|
-
// meta: {name,size,type,lastModified,fingerprint,chunkSize,totalChunks}
|
|
129
|
-
return { uploadId: meta.fingerprint, uploadedChunks: [] } // 或 { url } 表示秒传
|
|
130
|
-
},
|
|
131
|
-
async put({ uploadId, index, total, blob, file, meta, size, signal }) {
|
|
132
|
-
await myClient.send(blob, { index, signal })
|
|
133
|
-
return {} // 或 { url }
|
|
134
|
-
},
|
|
135
|
-
async complete({ uploadId, meta, total, uploaded, chunkResults, file }) {
|
|
136
|
-
return { url: 'https://…' } // 必须返回 url
|
|
137
|
-
},
|
|
138
|
-
async abort({ uploadId, meta, error }) {},
|
|
139
|
-
}
|
|
140
|
-
|
|
141
|
-
KEditor.create('#editor', { uploader: adapter, upload: { chunkSize: 2 * 1024 * 1024, concurrency: 2 } })
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
### 断点续传 / 秒传的判定依据
|
|
145
|
-
|
|
146
|
-
`meta.fingerprint` 默认由 `size + lastModified + 文件名` 组成(`upload.fingerprint: 'fast'`)。
|
|
147
|
-
改为 `'strong'` 时读取文件首尾各 256KB 计算 SHA-256(HTTPS / localhost 下可用),也允许传函数:
|
|
148
|
-
|
|
149
|
-
```js
|
|
150
|
-
upload: { fingerprint: async (file) => `${file.name}-${file.size}` }
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
服务端把 `identifier → 最终 url` 建索引即可实现秒传;把已落盘分片 index 列表返回即可续传。
|
|
154
|
-
|
|
155
|
-
---
|
|
156
|
-
|
|
157
|
-
## 4. 独立使用(不依赖编辑器)
|
|
158
|
-
|
|
159
|
-
```js
|
|
160
|
-
import { ChunkUploader, httpAdapter } from 'kyle-editor'
|
|
161
|
-
|
|
162
|
-
const uploader = new ChunkUploader(httpAdapter({ initUrl: '/api/upload/init', chunkUrl: '/api/upload/chunk', completeUrl: '/api/upload/complete' }), {
|
|
163
|
-
chunkSize: 4 * 1024 * 1024,
|
|
164
|
-
concurrency: 5,
|
|
165
|
-
retries: 3,
|
|
166
|
-
})
|
|
167
|
-
|
|
168
|
-
const ctrl = new AbortController()
|
|
169
|
-
const { url, chunks } = await uploader.upload(bigFile, {
|
|
170
|
-
signal: ctrl.signal,
|
|
171
|
-
onProgress: (ratio, info) => bar.style.width = `${info.percent}%`,
|
|
172
|
-
onChunk: ({ index, total }) => console.log(`${index + 1}/${total}`),
|
|
173
|
-
})
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
## 5. 编辑器内的交互契约
|
|
177
|
-
|
|
178
|
-
| 场景 | 行为 |
|
|
179
|
-
|------|------|
|
|
180
|
-
| 点击工具栏图片/视频 | 选择文件 → 就地插入占位块(含进度条、分片数、速度、取消按钮) |
|
|
181
|
-
| 拖拽文件到编辑区 | 光标定位到落点后插入占位块 |
|
|
182
|
-
| 粘贴截图 | 自动生成文件名并上传 |
|
|
183
|
-
| 上传成功 | 占位块替换为 `<img>` / `<video>`,图片支持双击放大、气泡工具条调整对齐/宽度/圆角/替换/删除、**拖拽右下角把手实时缩放** |
|
|
184
|
-
| 分片失败 | 自动重试 `retries` 次;仍失败则占位块转为错误态,提供「重试 / 移除」 |
|
|
185
|
-
| 取消 | `AbortController` 中止全部在传分片并调用 `abort()`,占位块移除 |
|
|
186
|
-
| 同一文件重复插入 | 适配器 `init` 返回 `url` 时直接秒传,不再切片 |
|