PaddleOCR JS 前端 SDK 开发指南：从环境安装到 npm 产物构建全流程解析

PaddleOCR JS 前端 SDK 开发指南从环境安装到 npm 产物构建全流程解析【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本文面向希望参与或深入理解 PaddleOCR JavaScript SDKpaddleocr-js的开发者完整讲解该 monorepo 的安装步骤、常用开发命令、TypeScript 工程规范、Vite 库模式构建流程与测试策略。读完本文你将掌握如何在本仓库中安装依赖、构建 SDK 与 demo、通过自定义 Vite 插件产出兼容 npm 分发的 Worker 产物并理解整个工程在浏览器端 OCR 场景下的设计取舍。所有命令与结论均以当前仓库实际代码为准涉及源码位置均已标注相对路径便于对照查阅。项目与文档背景paddleocr-js是 PaddleOCR 仓库中面向浏览器的 OCR SDK 子工程采用 npm workspaces 组织为 monorepo包含两个 workspacepackages/coreSDK 本体npm 包名为paddleocr/paddleocr-js基于 PaddleOCR 模型、ONNX Runtime Web 与 OpenCV.js在浏览器中完成文本检测、识别等推理见 packages/core/package.jsonapps/demo基于 Vite 的演示应用用于体验与联调 SDK 功能。本文对应的开发指南位于 paddleocr-js/docs/development.md另有中文版 paddleocr-js/docs/development_cn.md。下面的小节严格遵循该文档的脉络展开并补充仓库源码层面的实现细节。环境要求与依赖安装文档首先要求从paddleocr-js/根目录安装依赖npm install从根目录的 package.json 可以看到该工程通过workspaces字段声明了packages/*与apps/*因此一条npm install会统一安装 SDK、demo 以及根目录的工程化工具依赖。安装前请确认 Node.js 版本满足要求根工程与两个 workspace 的package.json中均声明了engines: { node: 20.11 }。SDK 核心依赖如下见 packages/core/package.json依赖作用onnxruntime-webORT JS 运行时负责模型推理与 WASM/WebGPU 后端techstark/opencv-jsOpenCV.js用于图像预处理等 CV 操作clipper-lib多边形裁剪库用于检测结果的几何后处理js-yamlYAML 解析用于模型配置文件的解析根目录还集成了 husky lint-staged 的 Git 提交钩子对*.{js,ts}文件在提交时执行eslint --fix与prettier --write对*.{json,md,html,css,yaml,yml}执行格式化见 package.json保证提交代码风格统一。常用命令速查文档给出了在paddleocr-js/根目录下可用的全部常用命令。对照根 package.json 的scripts字段逐条说明如下npm run build # 先构建 SDK 再构建 demo显式拓扑顺序 npm run build:sdk # 仅构建 SDKpackages/core npm run build:demo # 仅构建 demo 应用apps/demo npm run lint # 对整个仓库执行 ESLint 检查eslint . npm run test # 运行全部 Vitest 单元测试vitest run npm run typecheck # 对所有 workspace 执行 tsc --noEmit 类型检查 npm run check # 完整质量门禁format:check → lint → build:sdk → typecheck → test → build:demo npm run clean # 删除所有 dist/ 目录其中npm run build在根脚本中被定义为npm run build:sdk npm run build:demo通过保证了「先 SDK 后 demo」的显式构建顺序这正是文档所说的 topological order。npm run check是提交/发布前建议执行的全量校验任何一环失败都会中断。开发 demo 时使用 Vite 开发服务器npm run dev:demo该命令对应dev:demo: npm run dev --workspace apps/demo --实际在apps/demoworkspace 内启动 Vite。此外还有npm run preview:demo预览生产构建产物、npm run lint:fix、npm run test:watch、npm run test:coverage等补充脚本。如果需要单独操作某个 workspace可以像文档示例那样显式指定npm run build --workspace packages/core npm run build --workspace apps/demo发布流程对应脚本release: npm run build:sdk npm publish --workspace packages/core即先构建 SDK 再发布paddleocr/paddleocr-js。TypeScript 工程规范SDK 与 demo 均以 TypeScript 编写并开启严格模式文档明确了两点工程约定1. 两套 ESLint 规则集packages/**/src/与apps/**/src/下的源码使用typescript-eslint的strictTypeChecked规则集对类型安全要求最高packages/**/test/下的测试文件使用较轻的recommendedTypeChecked并放宽了no-unsafe-*与no-explicit-any等规则因为测试代码中常需要构造边界输入或进行类型断言。2. 统一的类型检查方式npm run typecheck对应npm run typecheck --workspaces --if-present会递归执行各 workspace 中的tsc --noEmitcore 与 demo 均定义了各自的typecheck脚本。关键点在于demo 的类型检查并不依赖先执行build:sdk。查看 apps/demo/tsconfig.json 可以看到demo 通过paths映射直接把paddleocr/paddleocr-js与paddleocr/paddleocr-js/viz指向packages/core/src下的 TypeScript 源码../../packages/core/src/index.ts、../../packages/core/src/viz/index.ts并额外 include 了../../packages/core/src/types/*.d.ts。因此 demo 始终对着最新源码做类型检查这也是文档强调「does not strictly require build:sdk to run first」的原因。SDK 自身的 tsconfig.json 还开启了declaration、declarationMap、sourceMap用于产出类型声明与源码映射rootDir限定为src。构建流程Vite 库模式与 dist 产物SDK 构建入口与产物结构SDK 使用 Vite 的库模式构建在packages/core中执行npm run build即vite build。从 packages/core/vite.config.ts 可以看到库入口有两个src/index.ts主入口与src/viz/index.ts可视化子路径输出格式仅es对外依赖onnxruntime-web、techstark/opencv-js、clipper-lib、js-yaml被标记为external不打包进产物由使用方自行提供开启了sourcemap且minify: false便于排查线上问题。构建后dist/下的产物与文档列出一致产物说明index.mjsESM 入口index.d.ts类型声明配合exports字段的types指向viz.mjs可视化子路径./viz的 ESM 入口assets/worker-entry-*.js自包含的 Worker bundle内含 OpenCV.js 与 ORT JS 运行时这些产物声明在 packages/core/package.json 的exports字段中主入口.与可视化子路径./viz均区分了types与default这正是浏览器端按需引入paddleocr/paddleocr-js与paddleocr/paddleocr-js/viz的依据。libraryWorkerPlugin面向 npm 分发的关键后处理Worker 是浏览器 OCR 的核心载体模型推理在 Worker 内执行避免阻塞主线程。但 Vite 默认产出「以站点根路径为基准」的绝对资源路径直接发布为 npm 包后下游使用方会因路径解析失败而无法加载 Worker。为此仓库在 packages/core/vite.config.ts 中实现了自定义插件libraryWorkerPlugin对构建产物做三步后处理第 1 步将 Worker 资源的绝对路径改写为相对路径Vite 注入的 Worker 引用形如/* vite-ignore */ /assets/worker-entry-xxx.js插件通过正则将其改写为./assets/worker-entry-xxx.js使文件相对于 SDK 模块自身位置解析而不是依赖站点根路径见 vite.config.ts。第 2 步拆分new Worker(new URL(...))模式插件把new Worker(new URL(./assets/..., import.meta.url), {...})重写为(() { const _w new URL(./assets/..., import.meta.url); return new Worker(_w, {...}); })();即先创建 URL 变量再构造 Worker见 vite.config.ts。这样做的目的是下游打包器如 Vite、webpack的资源复制插件可以识别并复制 Worker 文件而其 Worker 检测插件则不会把该文件当作二次打包目标避免重复处理导致产物异常。第 3 步剥离 base64 内联的 WASM 二进制Vite 会把 ORT 中new URL(./ort-wasm-*.wasm, import.meta.url)形式的引用转成data:application/wasm;base64,...数据 URI 并内联进 Worker据 vite.config.ts 的注释说明这会使 Worker 体积膨胀约 50 MB。插件在generateBundle阶段用正则data:application\/wasm;base64,...将这些 data URI 剥除仅保留前缀占位见 vite.config.ts。剥离后的 WASM 如何在运行时获得文档给出了答案Worker 模式下 ORT 通过ort.env.wasm.wasmPaths在运行时加载 WASM该路径由使用方配置未配置时回退到与安装 ORT 版本绑定的 CDN。仓库在构建期通过define注入__ORT_WASM_CDN_PREFIX__常量值为https://cdn.jsdelivr.net/npm/onnxruntime-web版本号/dist/版本号在构建时从onnxruntime-web包内读取见 vite.config.ts 与 vite.config.ts保证 CDN 回退路径与依赖版本严格一致。一个值得注意的实现细节WASM 剥离必须放在主构建的generateBundle钩子中而不是worker.rollupOptions.plugins里因为 Vite 是在 Worker 自身的 Rollup 流水线结束之后的「后处理」阶段才注入 data URI。同时剥离只针对data:application/wasmOpenCV.js 通过 Emscripten 内嵌的data:application/octet-streamWASM 必须保留——因为 OpenCV.js 没有等价的 CDN 回退机制见 vite.config.ts。demo 应用的开发与生产两套路径apps/demo的构建配置见 apps/demo/vite.config.js开发阶段npm run devVite 通过resolve.alias把paddleocr/paddleocr-js与paddleocr/paddleocr-js/viz直接指向packages/core/src的 TypeScript 源码实现即时 HMR热更新无需预先构建 SDK生产构建npm run buildalias 置空demo 通过 workspace 链接消费 SDK 预构建的dist/此时第 2 步的「兼容下游打包器的 Worker URL 形式」发挥作用Vite 能正确把 Worker 资源复制进 demo 的构建产物。另外demo 的server与preview配置都设置了Cross-Origin-Opener-Policy: same-origin与Cross-Origin-Embedder-Policy: credentialless响应头。这是浏览器端使用 WASM 线程如 ORT 的多线程后端时要求的跨源隔离相关设置开发与预览场景下保持一致避免本地调试与线上行为不一致。测试策略文档将测试策略概括为三层仓库中的测试文件见 packages/core/test与其一一对应1. 配置解析与注册表行为的单元测试对应model-config.test.ts、model-common.test.ts、ocr-config-branches.test.ts、resolve.test.ts等。SDK 依赖js-yaml解析 YAML 模型配置model-config.test.ts覆盖配置文件的解析与校验路径ocr-config-branches.test.ts则针对 OCR 配置的不同分支组合做断言验证配置解析的健壮性。2. 面向浏览器平台辅助函数的轻量级 jsdom 测试对应platform-browser.test.ts、browser-source.test.ts等。jsdom作为 devDependency见根 package.json用于模拟 DOM 环境测试浏览器平台相关的辅助逻辑无需启动真实浏览器。3. CI 默认不运行大规模真实模型推理仓库以轻量测试为主ocr-*、worker-*、runtime-*、pipelines-index.test.ts、public-api.test.ts等覆盖 API 面与 Worker 通信协议tar.test.ts配合tar-fixture.ts验证模型 tar 包解包逻辑viz-*系列覆盖可视化渲染画布工厂、颜色、绘制文本/框、字体等。这类测试不加载真实大模型保证 CI 在合理时间内完成。测试运行器为 Vitest根脚本test: vitest run支持test:watch与test:coverage两种开发辅助模式。总结一条可复现的 SDK 开发工作流综合文档与源码paddleocr-js的日常开发可按如下流程进行安装在paddleocr-js/根目录执行npm installNode.js ≥ 20.11开发调试npm run dev:demo启动 Vite 开发服务器通过 alias 直连 SDK 源码实现 HMR增量构建npm run build:sdk单独构建 SDK观察dist/产物index.mjs、viz.mjs、assets/worker-entry-*.js质量校验npm run check一次性执行格式化检查、lint、SDK 构建、类型检查、测试与 demo 构建发布npm run release先构建 SDK 再发布paddleocr/paddleocr-js到 npm。这套流程的核心价值在于libraryWorkerPlugin它让一个「自带 OpenCV.js ORT 运行时 Worker」的浏览器 OCR SDK 能以标准 npm 包形式分发同时通过运行时 WASM 加载ort.env.wasm.wasmPaths 版本绑定的 CDN 回退显著压缩了 Worker 体积。理解这三步后处理是排查「Worker 404」「Worker 被重复打包」「WASM 加载失败」等下游集成问题的关键也是后续为 SDK 扩展新功能如更多模型子路径、新的可视化能力时的构建基础。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考