同一套Go代码跑遍CLI与浏览器:make-look-scanned的WASM+PDF.js双端架构深度剖析
同一套Go代码跑遍CLI与浏览器:make-look-scanned的WASM+PDF.js双端架构深度剖析
make-look-scanned 是一个把 PDF"做旧"成真实扫描件效果的开源工具:它通过歪斜、灰度化、暖纸色调、扫描颗粒、失焦模糊、边缘暗角和 JPEG 压缩伪影,让电子文档看起来像普通扫描仪的输出。这个项目最有意思的地方在于同一套 Go 效果代码,既能在命令行(CLI)里跑,也能编译成 WebAssembly(WASM)在浏览器里离线运行——本文带你深入剖析这套 CLI + WASM + PDF.js 的双端架构是如何设计出来的。
一、先认识这个项目:一条流水线,两种形态 📄
整个流程可以概括为三步:
- 栅格化:把 PDF 每一页渲染成位图(CLI 端由 MuPDF 完成,浏览器端由 PDF.js 完成);
- 效果流水线:对位图依次施加灰度、纸色、模糊、噪点、暗角、歪斜等效果;
- 重新组装:把处理后的页面 JPEG 编码后打包成一份全新的"纯图片 PDF"——原来的可选中文本消失了,正符合"普通扫描仪不会输出可复制文本"的特征。
两种使用形态:
| 形态 | 构建产物 | 运行位置 | 适用场景 |
|---|---|---|---|
| CLI 版 | make-look-scanned 二进制 |
本机终端 | 批量处理、脚本化 |
| 浏览器版 | 单文件 HTML(约 8 MB) | 浏览器内 | 隐私优先、无需安装 |
CLI 的典型用法只有一行命令:
make-look-scanned in.pdf -o out.pdf --noise 0.4 --skew 2.5 --jpeg-quality 30
浏览器版则是打开一个自包含的 HTML 文件,选择 PDF、拖动滑块调参、点击"Scan PDF",全程文件不出本机。
二、架构分层的关键决策:把"渲染"单独拆出去 ✂️
双端架构的核心难题是:CLI 端用的 go-fitz(MuPDF 的 Go 绑定)通过 cgo 链接 C 库,无法编译到 js/wasm 平台,而浏览器里天然有 PDF.js 这个成熟的渲染器。
作者的解法非常干脆——按"平台相关性"对模块切分:
| 模块 | 路径 | CLI | 浏览器 | 说明 |
|---|---|---|---|---|
| 页面栅格化 | internal/render/render.go | ✅ | ❌ | 依赖 MuPDF/cgo,仅 CLI 使用 |
| 效果流水线 | internal/effects/pipeline.go | ✅ | ✅ | 纯 Go 共享代码,6 个效果各占一个文件 |
| PDF 组装 | internal/assemble/assemble.go | ✅ | ✅ | 纯 Go 共享代码,基于 gopdf |
| 预设配置 | internal/config/config.go | ✅ | — | 读取 config.toml 预设 |
| CLI 入口 | main.go | ✅ | — | 解析 flag、内容哈希种子 |
| WASM 入口 | cmd/wasm/main_js.go | — | ✅ | 向 JS 暴露 mls 对象 |
这里藏着一个刻意的设计细节:assemble 包只接收普通 *image.RGBA 图像加页面点数尺寸,而不依赖 render.Page 类型。包注释内部写得很直白:"这样它就不携带任何对栅格化器的依赖,从而能编译到 js/wasm"。换句话说,依赖方向被严格控制在"平台相关层 → 纯 Go 共享层"这一个方向上,WASM 编译时只是把平台相关的入口和 render 包换掉而已。
三、CLI 端:main.go 如何串起整条流水线 🚀
CLI 入口 main.go 的 run() 函数就是完整的编排逻辑:
- 解析参数:除了常规 flag,还做了一次"二次解析",允许 flag 出现在文件名前后任意位置(见 main.go 的注释,标准库
flag遇到第一个位置参数就停止解析,作者手动补回了后续参数); - 解析预设:内置默认值 →
config.toml预设 → 显式 CLI flag,三者优先级递增; - 确定性种子:默认用输入 PDF 内容的 FNV-1a 64 位哈希作为随机种子(contentSeed),同一份文件永远生成同一份"扫描件";指定
--seed N可换一个可复现的新外观; - 逐页处理:每页独立派生种子(
baseSeed ^ int64(i)*0x9E3779B9,见 main.go),再交给effects.Run; - 组装输出:
assemble.Write输出 PDF,打印页数。
效果流水线本身在 internal/effects/pipeline.go 中,顺序固定且"顺序有讲究":
grayscale → paperTone → blur → noise → edgeShadow → skew
页面先调色调、加颗粒,最后才旋转——这样前面所有效果都会跟着页面一起歪斜,更符合真实扫描的物理直觉。还有一个精巧的细节:噪点和歪斜各自使用独立派生的随机数生成器,避免"一个效果消耗多少随机数会干扰下一个效果"的耦合(比如 DPI 变了、像素变多,歪斜角度就会漂移)。
至于字节级确定性,功劳要记在 internal/assemble/assemble.go 选用的 gopdf 头上:它按固定顺序序列化页面和图片、不写入时间戳,所以相同输入 + 相同种子 = 字节级完全一致的输出;注释还说明了为什么放弃另一个流行库 fpdf(它的图片嵌入顺序依赖 Go map 遍历的随机性)。
四、浏览器端:PDF.js 与 Go WASM 的分工 🌐
浏览器端由两个文件协作完成:
- PDF.js(JS 侧):负责把每一页渲染到 canvas,再用
getImageData取出原始 RGBA 像素; - Go WASM 模块(编译自
cmd/wasm/):负责全部 6 个效果 + PDF 组装,与 CLI 完全同源。
4.1 用构建标签区分双入口
cmd/wasm/ 目录下只有两个文件:
- main_js.go:文件首行是
//go:build js && wasm,仅在 WASM 构建时参与编译; - main_other.go:
//go:build !(js && wasm),一个空main()桩,保证go build ./...、go vet ./...在任何平台上都不报错。
这是 Go 多平台项目最标准的"双入口"写法,成本几乎为零。
4.2 JS 侧的 API 设计
WASM 入口在 main_js.go 向全局挂了一个 mls 对象,暴露三个函数,对应浏览器处理的三个阶段:
| JS API | 作用 | 对应 CLI 概念 |
|---|---|---|
mls.reset(params) |
设置并校验参数,清空累积页面 | 解析 flag + 预设 |
mls.addPage(rgba, w, h, widthPt, heightPt) |
接收一页原始 RGBA 像素,跑效果流水线后累积 | 单页 effects.Run |
mls.build() |
组装全部页面,返回 PDF 字节(Uint8Array) |
assemble.Write |
参数对象用 camelCase 镜像 CLI flag 名(paperTone、edgeShadow、jpegQuality……),降低了两端的心智转换成本。有个小坑值得注意:种子是一个 64 位整数,塞不进 JS 的 number,所以约定用十进制字符串传递(main_js.go)。
4.3 前端胶水逻辑
web/index.html 里的"Scan PDF"按钮是整个浏览器的流程中心:
PDF.js 加载文档 → 逐页 getViewport(DPI/72) → 渲染到 canvas
→ getImageData 取 RGBA → mls.addPage(...)
→ 全部页完成 → mls.build() → Blob → iframe 预览 + 下载链接
值得注意的是种子的跨语言复刻:JS 侧用 BigInt 手写了一份 FNV-1a 64 位实现(index.html),与 Go 端的 contentSeed 完全对齐,因此浏览器版同样默认"同一文件 → 同一结果"。
最后一个坦率的细节:浏览器输出与 CLI 视觉等价但并非字节级一致,因为 PDF.js 与 MuPDF 的栅格化结果本身存在细微差异——共享的是效果与组装,不是像素。
五、构建与分发:从开发服务器到单文件离线版 📦
5.1 开发模式
git clone https://gitcode.com/gh_mirrors/mak/make-look-scanned
cd make-look-scanned
./web/build.sh # GOOS=js GOARCH=wasm go build -o web/main.wasm ./cmd/wasm
(cd web && python3 -m http.server 8080) # 打开 http://localhost:8080
web/build.sh 还顺手从 GOROOT 复制了 Go 运行时胶水 wasm_exec.js。
5.2 单文件离线版
task build:web # 产出 dist/make-look-scanned.html(约 8 MB)
这条命令由 Taskfile.yml 编排,先跑 web/build.sh,再执行 web/bundle.py 做"内联打包":把 wasm_exec.js、PDF.js 的 ESM 库、PDF.js worker、main.wasm 全部以 base64 形式塞进 HTML 的 <script type="text/plain"> 块,运行时解码为 Blob。于是得到一个双击即开、断网可用、零服务器依赖的单文件应用。
web/bundle.py 里有个讲究:选 base64 正是因为 base64 字符集不含 <,内容永远不可能提前闭合 <script> 标签造成"脚本逃逸",内联才安全。
5.3 质量保障
Taskfile.yml 的 lint 任务除了常规的 go fix/gofmt,还额外跑了一句 GOOS=js GOARCH=wasm go vet ./cmd/wasm——WASM 目标被纳入日常静态检查,防止"浏览器版本悄悄烂掉"。
六、给新手的双端架构要点清单 📝
从 make-look-scanned 身上,可以提炼出这几条可复用的工程经验:
- 按平台相关性分层:cgo/原生依赖(MuPDF)只允许出现在"边缘层"(栅格化 + CLI 入口),核心业务(效果 + 组装)保持纯 Go,WASM 编译就是"换头不换身";
- 依赖方向要可检验:
assemble拒绝依赖render.Page,用类型边界保证自己"可编译到任何平台"; - 构建标签是零成本的双入口方案:两个
main.go+ 两个 build tag,互不干扰; - 确定性靠种子不靠运气:内容哈希做默认种子 + 每页种子独立派生 + 无时间戳的 PDF 序列化器,三件套保证字节级可复现;
- 分发体验决定传播半径:用 base64 内联把 wasm、JS、PDF.js 压进一个 HTML,把"需要装 Go、装 C 工具链"的门槛降到"双击打开"。
如果你正在做一个想同时覆盖终端与浏览器的 Go 图像处理工具,make-look-scanned 的模块划分(internal/ + cmd/wasm/ + web/)几乎可以直接照搬。