SiYuan 图片文字识别完整指南：3 步从图片批量提取文字-创锋一号

SiYuan 图片文字识别完整指南：3 步从图片批量提取文字

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

本文从会议照片、截图文献这类真实场景出发，介绍 SiYuan 如何借助开源 Tesseract OCR 引擎，把图片里的文字转成可搜索、可编辑的纯文本。内容涵盖环境检查、三步操作、识别语言包与参数配置、常见故障排查，帮你在右键菜单里一次完成 SiYuan 图片文字识别。

两个让人头疼的场景

客户会议拍的白板照片，板书内容想抄进纪要，只能对着照片手打一遍；
从 PDF 翻拍的图表注释，鼠标框选复制不到字，全文搜索也搜不到这张图里的内容。

这类"文字在图里"的素材，传统做法是单独开 OCR 软件、导出、再粘贴回笔记，链路很长。SiYuan 的做法是一句话能说清的：内置调用系统里的 Tesseract OCR，图片粘贴进笔记后自动后台识别，结果直接落库，右键菜单随时查看和复制。

如何启用 SiYuan 图片文字识别：先装好 Tesseract

SiYuan 本身不打包 Tesseract，它启动时自动检测系统命令，所以第一步是装好依赖：

Windows：choco install tesseract
macOS：brew install tesseract
Linux（Debian/Ubuntu）：sudo apt install tesseract-ocr tesseract-ocr-chi-sim（按需加装其他语言包）

装完重启 SiYuan，在日志里看到类似这一行，说明功能已就绪：

tesseract-ocr enabled [ver=5.3.3, maxSize=2.0MB, langs=eng+chi_sim]

如果只有一行告警或菜单里找不到 OCR 项，通常是 tesseract 不在 PATH 里（macOS 装完后偶发）。SiYuan 会依次尝试/usr/local/bin/tesseract和/opt/homebrew/bin/tesseract两个常见位置，仍找不到就按上面的命令重装一次。

三步拿到识别结果：粘贴、右键、复制

把图片放进笔记：直接把会议照片拖进编辑区，或复制粘贴。png、jpg、jpeg、tiff、bmp、webp、gif 等常见位图格式都支持，单张默认上限 2MB。
等后台识别：无需任何操作，新图片会自动进入 OCR 队列，在空闲时段被后台任务处理（每轮最多处理 7 张，避免占满资源）。识别进度会显示在右下角状态栏。
右键查看文字：在图片上点右键，进入 OCR 子菜单，识别文本直接显示在一个文本框里，可复制、可修正；觉得结果不对，选"重新 OCR"即可强制重跑一次。

识别出的文字不只是"看一眼"，它会写进工作区的索引，之后全文搜索能直接搜到图里的句子，这正是把截图文献变成可检索知识的价值所在。

识别语言包怎么选，参数在哪里调

SiYuan 默认加载系统里已安装的中英文、日语等主流语言包（英文、简繁中文、日、法、西、德、俄及方向检测）。想自定义行为，用环境变量控制即可，均在启动前设置：

环境变量	作用	示例
`SIYUAN_TESSERACT_LANGS`	限定识别语言组合，`+`连接	`SIYUAN_TESSERACT_LANGS=chi_sim+eng`
`SIYUAN_TESSERACT_MAX_SIZE`	单张图片大小上限（字节），默认 2000000	`SIYUAN_TESSERACT_MAX_SIZE=5000000`
`SIYUAN_TESSERACT_TIMEOUT`	单张识别超时时间（毫秒），默认 7000	`SIYUAN_TESSERACT_TIMEOUT=15000`
`SIYUAN_TESSERACT_ENABLED`	临时关闭 OCR 功能	`SIYUAN_TESSERACT_ENABLED=false`

语言包选择建议：只选图片里真实出现的语言。多塞语言包不会让结果更准，反而可能干扰语种判断；比如纯中文会议纪要，chi_sim+eng就够了。注意SIYUAN_TESSERACT_LANGS是"在已安装语言里做筛选"，写进去但系统没装的语言包会被自动跳过，不会报错。

批量处理图片文字也不用挑文件：把素材陆续拖进笔记即可，后台任务会一轮一轮地把未识别的图片消化完，已经出过结果的图片不会重复处理。

图片文字识别常见问题排查

现象	可能原因	处理办法
右键没有 OCR 菜单，或提示"Tesseract OCR 未安装或未配置"	tesseract 未安装或不在 PATH	按上文安装命令重装，重启 SiYuan 后看日志确认`tesseract-ocr enabled`
结果乱码、整段英文识别成拼音	缺少对应语言包	安装对应语言包（如`tesseract-ocr-chi-sim`），并用`SIYUAN_TESSERACT_LANGS`指定组合
大图识别不到、菜单里无结果	超过默认 2MB 上限	先压缩图片，或调大`SIYUAN_TESSERACT_MAX_SIZE`
识别中途无结果，日志有 timeout 记录	单张耗时超过 7 秒默认超时	调大`SIYUAN_TESSERACT_TIMEOUT`，或换清晰度更高的原图
手写体识别率低	引擎对手写支持有限，属正常情况	关键内容人工修正一次，"重新 OCR"前可先把文字框里的内容留档

另有一个容易忽略的点：加密笔记本里的图片是密文，SiYuan 会主动跳过其 OCR，避免垃圾文本污染搜索索引。

小结与进阶提示

启用流程就三件事：装 Tesseract → 重启 SiYuan → 把图片拖进笔记，剩下的交给后台任务；
识别结果缓存在工作区assets/ocr-texts.json，重启不丢失，重复图片不重复计算；
想理解或扩展行为，核心逻辑都在这几个文件里：kernel/util/ocr.go（Tesseract 调用与结果解析）、kernel/model/ocr.go（后台自动 OCR 任务）、app/src/menus/protyle.ts（右键菜单入口），改动前建议先读懂再加环境变量；
需要源码自行编译时，可执行git clone https://gitcode.com/GitHub_Trending/si/siyuan获取仓库。

对会议照片整理这类高频场景，建议把语言包固定成chi_sim+eng，把单张上限适度调大。用一周左右你会发现，截图素材终于能被全文搜索"看见"了。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析