@duoyun/md-img-pull 1.0.0
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 +85 -0
- package/dist/main.cjs +31309 -0
- package/package.json +51 -0
package/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# md-img-pull
|
|
2
|
+
|
|
3
|
+
一个用于将 Markdown 中的网络图片下载到本地、统一重写引用路径并对超大图片进行压缩的命令行工具。适合将笔记、博客中的媒体资源“本地化”，让内容更可移植、更易备份。
|
|
4
|
+
|
|
5
|
+
## 功能概述
|
|
6
|
+
|
|
7
|
+
- 递归扫描文件夹或处理单个 `.md` 文件
|
|
8
|
+
- 仅处理以 `http` 开头的图片链接，已本地化的相对/本地路径会跳过
|
|
9
|
+
- 将图片保存到目标 Markdown 同级的 `assets/` 目录，文件名为内容哈希
|
|
10
|
+
- 对超过阈值的图片自动压缩，必要时统一转为 WebP，尽量保留动画
|
|
11
|
+
- 使用并发控制与进度动画，清晰显示下载/压缩过程
|
|
12
|
+
- 输出详细的处理日志（成功/失败、尺寸变化）到目标目录
|
|
13
|
+
|
|
14
|
+
## 安装
|
|
15
|
+
|
|
16
|
+
- 全局安装（如果已发布到 npm）：
|
|
17
|
+
- `npm i -g @duoyun/md-img-pull` 或 `pnpm add -g @duoyun/md-img-pull`
|
|
18
|
+
- 命令：`md-img-p`
|
|
19
|
+
- 本地构建运行（当前仓库）：
|
|
20
|
+
- 安装依赖：`pnpm i`
|
|
21
|
+
- 构建：`pnpm build`
|
|
22
|
+
- 运行：`node dist/main.cjs`
|
|
23
|
+
|
|
24
|
+
环境要求：推荐 Node.js ≥ 18。依赖 `sharp`，在常见平台会自动下载所需的 libvips。
|
|
25
|
+
|
|
26
|
+
## 使用说明
|
|
27
|
+
|
|
28
|
+
- 运行后按提示输入源路径，可以是：
|
|
29
|
+
- 某个 Markdown 文件路径，例如 `C:\Notes\foo.md`
|
|
30
|
+
- 某个目录路径，例如 `C:\Notes`
|
|
31
|
+
- 输出位置：
|
|
32
|
+
- 单文件模式：在同目录生成 `foo_localized/`，并包含 `assets/`
|
|
33
|
+
- 目录模式：在同级生成 `Notes_localized/`，保持原有层级结构与 `assets/`
|
|
34
|
+
- 若目标目录已存在，会进行交互确认；按回车或输入 `y/yes` 继续，输入 `n` 取消
|
|
35
|
+
|
|
36
|
+
示例（本地构建后运行）：
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
node dist/main.cjs
|
|
40
|
+
# 请输入或粘贴需要处理的源文件夹路径: C:\Users\me\Desktop\Notes
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## 处理策略
|
|
44
|
+
|
|
45
|
+
- 下载与重写
|
|
46
|
+
- 遍历 Markdown AST 中的 `image` 节点，仅处理 `http` 开头的链接
|
|
47
|
+
- 保存为 `assets/<hash>.<ext>` 并将 Markdown 中的 URL 改为相对路径 `./assets/<hash>.<ext>`
|
|
48
|
+
- 并发与大图串行
|
|
49
|
+
- 总并发槽位数为 5
|
|
50
|
+
- 普通图片占用 1 槽位并发下载
|
|
51
|
+
- 超大图片（> 20MB）会“独占”全部槽位，串行下载与压缩，避免内存与带宽拥塞
|
|
52
|
+
- 压缩与格式
|
|
53
|
+
- 基准目标：将图片控制在 10MB 内
|
|
54
|
+
- 首先尝试转 WebP（quality≈80）；仍超出则缩放至最大宽度 2560 并再压缩；最后“保底”极限压缩（quality≈60）
|
|
55
|
+
- 如果发生压缩/转码，最终扩展名会改为 `.webp`；SVG 不参与压缩与改码
|
|
56
|
+
- 进度与日志
|
|
57
|
+
- 使用优雅的命令行进度动画显示当前下载项目与累计进度
|
|
58
|
+
- 处理完成后在输出目录生成 `image-log-*.txt`，记录成功/失败、尺寸变化与汇总统计
|
|
59
|
+
|
|
60
|
+
## 常见问答
|
|
61
|
+
|
|
62
|
+
- 已有本地图片会被重复处理吗？不会，工具仅处理 `http` 链接。
|
|
63
|
+
- 动图是否保留？在支持的情况下，WebP 保留原始 GIF/APNG 的动画（由 `sharp` 处理）。
|
|
64
|
+
- 我能调整并发或压缩阈值吗？可以，修改源码中的常量后重新构建：
|
|
65
|
+
- 并发与大图阈值：[`Semaphore.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/Semaphore.ts)
|
|
66
|
+
- 压缩目标与质量：[`imageCompression.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/imageCompression.ts)
|
|
67
|
+
|
|
68
|
+
## 代码入口与关键模块
|
|
69
|
+
|
|
70
|
+
- CLI 入口与交互：[`main.ts`](file:///c:/Users/37524/Desktop/md-img-pull/main.ts)
|
|
71
|
+
- Markdown 解析与图片节点收集：[`processSingleMarkdown.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/processSingleMarkdown.ts)
|
|
72
|
+
- 下载、本地化与重写：[`downloader.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/downloader.ts)
|
|
73
|
+
- 并发控制（信号量）：[`Semaphore.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/Semaphore.ts)
|
|
74
|
+
- 下载进度动画：[`downloadProgress.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/downloadProgress.ts)
|
|
75
|
+
- 处理日志管理：[`imageLog.ts`](file:///c:/Users/37524/Desktop/md-img-pull/utils/imageLog.ts)
|
|
76
|
+
|
|
77
|
+
## 构建与发布
|
|
78
|
+
|
|
79
|
+
- 使用 `esbuild` 打包为 CJS，并通过 `bin` 暴露命令 `md-img-p`
|
|
80
|
+
- 打包脚本：`pnpm build`
|
|
81
|
+
- 包配置与入口：[`package.json`](file:///c:/Users/37524/Desktop/md-img-pull/package.json)
|
|
82
|
+
|
|
83
|
+
## 许可
|
|
84
|
+
|
|
85
|
+
ISC License
|