Coze Studio 前端工程解析:coze-arch/pdfjs-shadow 如何收敛 pdfjs-dist 的 Worker 初始化与资源寻址【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio本篇技术文章围绕coze-arch/pdfjs-shadow包的设计目的与源码实现展开:它为何要在 Monorepo 中为 pdfjs-dist 建立一层影子封装、workerSrc的 URL 是如何统一计算并指向 CDN 的、以及前端各业务包应如何正确地消费该能力。读完后,你将掌握该包的完整 API 面、区域(CN/海外)资源寻址规则、幂等初始化机制及其对应的测试证据,能够在 Coze Studio 前端工程中正确接入 PDF 解析能力。为什么需要 shadow 包:pdfjs-dist 的兼容性问题该包的 README 开宗明义地说明了设计动机:原始的 pdfjs-dist 包兼容性过低,需要重新编译,增加 polyfill 之后才能正常运行,因此设计该 package。在此基础上,README 明确了两条核心设计目标:收敛 pdfjs-dist 调用,避免 bot 环境中多出(多个)定义 pdfjs-dist 版本;收敛 worker src url 的计算逻辑。同时 README 特别标注:该 package 仅供 coze 消费——它不是面向外部发布物的通用组件,而是 Coze 前端 Monorepo 内部的基础设施包,这也解释了它出现在 前端禁用第三方库清单中扮演的白名单替代者角色。pdfjs-dist 本身是 Mozilla 开源的 PDF 解析库,其典型用法包含两个关键动作:一是设置GlobalWorkerOptions.workerSrc指向pdf.worker资源,二是通过getDocument加载文档(可选传入cMapUrl指向字体映射 cmaps 目录)。这两个动作都依赖资源文件的 URL 从哪里来——这正是该包统一收口解决的问题。包结构、构建配置与依赖锁定从源码结构看,该包位于 frontend/packages/arch/pdfjs-shadow 目录下,结构如下:src/index.ts:统一导出入口(API 面);src/init-pdfjs-dist.ts:worker 初始化实现;src/generate-assets.ts:CDN 资源 URL 生成逻辑;src/global.d.ts:全局类型声明;scripts/const.ts:构建输出目录常量;__tests__/:三个 vitest 测试文件。关键构建与元信息集中在 package.json 中,几个字段值得注意:{ name: coze-arch/pdfjs-shadow, main: src/index.ts, unpkg: ./lib, types: ./src/index.ts, files: [lib, README.md], scripts: { build: tsc -b tsconfig.build.json node -r sucrase/register scripts/build.ts, test: vitest --run --passWithNoTests }, devDependencies: { pdfjs-dist: 4.3.136, core-js: ^3.37.1, esbuild: ^0.15.18 }, botPublishConfig: { main: lib/worker.js } }从这些配置可以确认以下事实:pdfjs-dist 版本被锁定在4.3.136,且仅作为该包的 devDependency 存在。配合 devDependencies 中的core-js与esbuild,与 README 中重新编译,增加 polyfill的说法相互印证:polyfill 与重编译发生在该包的构建阶段,消费方拿到的已经是可运行的产物;源码入口src/index.ts直接作为main与types,说明在 Monorepo 开发态下,业务包直接以 TS 源码消费该包,类型链路完整;unpkg: ./lib与files: [lib, README.md]表明发布产物是构建后的lib/目录;botPublishConfig.main指向lib/worker.js,说明构建会产出一个独立的 worker 文件供发布环境使用;scripts/const.ts 中定义了构建输出目录:export const OUTPUT_DIR path.resolve(__dirname, ../lib);即构建产物统一落盘到包根目录下的lib/,与unpkg字段及 CDN 路径约定(见下文)对应。API 面:统一收敛的 pdfjs-dist 调用入口包的完整导出面定义在 src/index.ts:export { getDocument, type PDFDocumentProxy, type PDFPageProxy, type PageViewport, } from pdfjs-dist; export { type TextContent } from pdfjs-dist/types/src/display/text_layer; export { type TextItem } from pdfjs-dist/types/src/display/api; export { generatePdfAssetsUrl } from ./generate-assets; export { initPdfJsWorker } from ./init-pdfjs-dist;这个导出面体现了 README 第一条目标——收敛 pdfjs-dist 调用的具体做法:消费方不再直接import from pdfjs-dist,而是只从coze-arch/pdfjs-shadow导入getDocument、核心类型(PDFDocumentProxy、PDFPageProxy、PageViewport、TextContent、TextItem)以及两个工具函数。pdfjs-dist 的实现细节与版本被完全隔离在这一层之后。这种收敛不只是约定,仓库层面还有强制手段:frontend/disallowed_3rd_libraries.json 中明确登记了[pdfjs-dist, null, 请使用 coze-arch/pdfjs-shadow 代替]即 lint 规则直接禁止业务包依赖裸的 pdfjs-dist,违规引用会被工程链路拦截。这是避免 bot 环境中多出 pdfjs-dist 版本这一目标得以落地的治理保障——无论业务侧多少处用到 PDF 能力,依赖图里只有这一个包持有 pdfjs-dist。仓库中有两类真实消费方可以佐证这一设计:其一,链接预览场景。json-link-preview 的 PDF 预览插件 在模块顶层完成初始化,再调用getDocument加载远程 PDF:import { initPdfJsWorker, getDocument, generatePdfAssetsUrl, type PDFDocumentProxy, } from coze-arch/pdfjs-shadow; initPdfJsWorker(); // ... useEffect(() { getDocument({ url: src, cMapUrl: generatePdfAssetsUrl(cmaps), }) .promise.then(pdf { setPdfDoc(pdf); setPageCount(pdf.numPages); }) // ... }, [src]);这里能看到该包 API 的典型组合:initPdfJsWorker()先执行一次,getDocument传入cMapUrl(即 cmaps 字体映射目录),后续通过pdfDoc.getPage(pageNumber)page.render(...)将页面渲染到canvas上,并处理设备像素比(devicePixelRatio)缩放。其二,知识库文件上传校验场景。knowledge-resource-processor-base 的上传前置校验 采用动态 import,避免 PDF 库进入非 PDF 文件的打包 chunk:const pdfjs await import(coze-arch/pdfjs-shadow); const { getDocument, initPdfJsWorker } pdfjs; initPdfJsWorker(); const uint8Array await getUint8Array(fileInstance); const pdfDocument await getDocument({ data: uint8Array }).promise; if (pdfDocument.numPages PDF_MAX_PAGES) { // 超出页数上限,提示用户并中断上传 }两个消费方均通过workspace:*方式声明依赖(见 knowledge-resource-processor-base/package.json 与 knowledge-resource-processor-core/package.json),进一步确认了版本单一来源。initPdfJsWorker:幂等的 workerSrc 初始化第二个导出函数负责 README 所述收敛 worker src url 的计算逻辑。完整实现见 src/init-pdfjs-dist.ts:import { GlobalWorkerOptions } from pdfjs-dist; import { generatePdfAssetsUrl } from ./generate-assets; /** * This method is used to initialize the workerSrc parameter of pdfjs-dist, which can be called repeatedly */ export const initPdfJsWorker () { if (!GlobalWorkerOptions.workerSrc) { GlobalWorkerOptions.workerSrc generatePdfAssetsUrl(pdf.worker); } };实现上有三个要点:只写不覆盖:仅当GlobalWorkerOptions.workerSrc为空时才赋值。这意味着函数是幂等的,可以在任意模块顶层安全地重复调用(如上面preview.tsx的模块级调用),且不会覆盖调用方或测试环境已显式设置的 worker 地址;URL 计算委托给generatePdfAssetsUrl(pdf.worker):worker 资源地址的计算逻辑完全收口在包内,业务侧无需关心 CDN 域名、版本与区域;注释明确声明可重复调用(can be called repeatedly),这与幂等实现一致。对应测试tests/init-pdfjs-dist.test.ts 用 vitest 的vi.mock模拟pdfjs-dist与generate-assets两个模块,覆盖两条路径:workerSrc 为空时:调用后generatePdfAssetsUrl恰被调用一次且参数为pdf.worker,workerSrc 被设置为生成的 URL;workerSrc 已有值(existing-worker-url)时:再次调用不会触发generatePdfAssetsUrl,原值保持不变。generatePdfAssetsUrl:面向 CDN 的区域化资源寻址worker 地址的来源就是 src/generate-assets.ts,这是整个包中最体现计算逻辑收敛的部分:import pkg from ../package.json; type AssetsType cmaps | pdf.worker; // Here you need to write the version that bnpm has released. const DEFAULT_VERSION 0.1.0-alpha.x6e892414ec; /** * This method is used to produce the worker cmaps link of the unpkg environment. Note that it is not a native method of pdfjs */ export const generatePdfAssetsUrl (assets: AssetsType) { const { name } pkg; let assetsUrl; switch (assets) { case cmaps: { assetsUrl lib/cmaps/; break; } case pdf.worker: { assetsUrl lib/worker.js; break; } default: { throw new Error( 目前只支持引用 cmaps 与 pdf.worker 文件,如需引用其他文件请联系 fanwenjie.fe, ); } } const onlinePkgName name.replace(/^/, ); const domain REGION cn ? lf-cdn.coze.cn/obj/unpkg : sf-cdn.coze.com/obj/unpkg-va; // cp-disable-next-line return //${domain}/${onlinePkgName}/${DEFAULT_VERSION}/${assetsUrl}; }结合tests/generate-assets.test.ts 的用例,可以完整梳理其寻址规则:1. 资源类型白名单(assets)维度。函数签名限定入参为AssetsType cmaps | pdf.worker,分别映射到包内lib/产物中的两个路径:入参映射路径用途cmapslib/cmaps/传给getDocument的cMapUrl,字体映射(字符码映射)文件目录pdf.workerlib/worker.js传给GlobalWorkerOptions.workerSrc,PDF 解析 worker传入其他值会直接抛出错误(目前只支持引用 cmaps 与 pdf.worker 文件),测试中generatePdfAssetsUrl(invalid as any)的断言验证了这一失败路径。白名单化的目的是把哪些文件可以放在 CDN 上被引用控制到最小集。2. 区域(REGION)维度。全局常量REGION决定 CDN 域名(类型见 src/global.d.ts 中的declare const REGION: cn | sg | va):REGIONCDN 域名完整路径示例(pdf.worker)cnlf-cdn.coze.cn/obj/unpkg//lf-cdn.coze.cn/obj/unpkg/coze-arch/pdfjs-shadow/0.1.0-alpha.x6e892414ec/lib/worker.jssg/va(非 cn)sf-cdn.coze.com/obj/unpkg-va//sf-cdn.coze.com/obj/unpkg-va/coze-arch/pdfjs-shadow/0.1.0-alpha.x6e892414ec/lib/worker.js测试用例覆盖了 CN 与va两个区域下 cmaps、worker 共四种组合,均断言了域名、去 scope 后的包名(pkg.name.replace(/^/, ),即coze-arch/pdfjs-shadow→coze-arch/pdfjs-shadow)与资源路径三个要素。注意最终 URL 以//开头(协议相对),协议由页面环境决定。3. 版本维度。DEFAULT_VERSION硬编码为0.1.0-alpha.x6e892414ec,源码注释Here you need to write the version that bnpm has released表明该值需要与该包实际发布到内部 npm 源(bnpm)的版本保持同步——也就是说,CDN 上的资源版本是发布时锁定的,更新 CDN 资源后需要同步修改该常量。这是一个从源码结构看可以推断的运维约束:版本常量、lib/产物与 CDN 上传三者必须一致。全局类型声明:补齐 worker 模块与 REGION 常量src/global.d.ts 提供了三处环境声明,它们解释了上面几个实现细节何以能通过 TS 编译:/// reference typespdfjs-dist / declare module pdfjs-dist/build/pdf.worker.mjs; declare module pdfjs-dist/build/pdf.worker.entry.js; declare const REGION: cn | sg | va;两个declare module为 pdfjs-dist 的 worker 构建产物补上模块类型声明,使构建脚本能够以模块导入方式处理 worker 文件;REGION被声明为编译期注入的全局常量(取值cn | sg | va),运行时由构建/运行环境定义。这也意味着区域寻址不是函数入参,而是部署形态的一部分:同一份代码构建到不同区域环境时,REGION的值决定 CDN 域名;顶部/// reference typespdfjs-dist /引入 pdfjs-dist 的完整类型,支撑src/index.ts中的类型再导出。测试覆盖总览该包在tests目录下维护三个 vitest 测试文件,与 vitest.config.ts 配合执行(npm run test):index.test.ts:验证入口导出面,保证 API 收敛契约稳定;init-pdfjs-dist.test.ts:验证幂等初始化——空值时设置、已有值时不覆盖(见上文引用);generate-assets.test.ts:验证 CN/海外双区域 × cmaps/worker 的资源 URL 生成,以及非法资源类型的异常抛出,并在afterEach中恢复global.REGION。测试对pdfjs-dist与generate-assets均采用vi.mock隔离,保证被测模块行为可断言,这也是一层封装型包应有的测试姿势:不依赖真实 CDN 与真实 pdfjs-dist 运行时。在 Coze 前端工程中使用该包的完整姿势综合源码与真实消费方,在 Monorepo 中接入 PDF 能力的标准流程是:声明 workspace 依赖:在业务包package.json中添加coze-arch/pdfjs-shadow: workspace:*,不要直接依赖pdfjs-dist(会被 disallowed_3rd_libraries.json 的 lint 规则拦截);初始化 worker:在模块顶层或按需调用initPdfJsWorker(),该函数幂等,可放心重复调用;加载文档:import { initPdfJsWorker, getDocument, generatePdfAssetsUrl, } from coze-arch/pdfjs-shadow; initPdfJsWorker(); const pdf await getDocument({ url: pdfUrl, // 远程 URL 场景 // 或 data: uint8Array, // 本地文件/内存数据场景 cMapUrl: generatePdfAssetsUrl(cmaps), // 中文等复杂字形需要 cmaps 支持 }).promise;渲染与翻页:使用pdf.numPages获取页数,pdf.getPage(n)获取页面代理,page.getViewport({ scale })计算视口(通常叠加devicePixelRatio处理高分屏),最终page.render({ canvasContext, viewport, ... })绘制到 canvas;性能考量:对非 PDF 主路径的代码,参考知识库上传校验的实现,使用await import(coze-arch/pdfjs-shadow)动态引入,将 PDF 库排除出首屏主 chunk。小结coze-arch/pdfjs-shadow是一个典型的依赖收敛层设计:它以约两个百行的核心源码(src/index.ts、src/init-pdfjs-dist.ts、src/generate-assets.ts)解决了三个工程问题——pdfjs-dist 版本单一来源(配合 lint 强制规则)、worker 资源 URL 的幂等初始化、以及面向 CN/海外区域的 CDN 资源寻址白名单。对于在 Coze Studio 前端 Monorepo 中新增 PDF 相关功能的开发者,只需记住一件事:一切 PDF 解析入口都从coze-arch/pdfjs-shadow走,而不是pdfjs-dist本身。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Coze Studio 前端工程解析:@coze-arch/pdfjs-shadow 如何收敛 pdfjs-dist 的 Worker 初始化与资源寻址
Coze Studio 前端工程解析:coze-arch/pdfjs-shadow 如何收敛 pdfjs-dist 的 Worker 初始化与资源寻址【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio本篇技术文章围绕coze-arch/pdfjs-shadow包的设计目的与源码实现展开:它为何要在 Monorepo 中为 pdfjs-dist 建立一层影子封装、workerSrc的 URL 是如何统一计算并指向 CDN 的、以及前端各业务包应如何正确地消费该能力。读完后,你将掌握该包的完整 API 面、区域(CN/海外)资源寻址规则、幂等初始化机制及其对应的测试证据,能够在 Coze Studio 前端工程中正确接入 PDF 解析能力。为什么需要 shadow 包:pdfjs-dist 的兼容性问题该包的 README 开宗明义地说明了设计动机:原始的 pdfjs-dist 包兼容性过低,需要重新编译,增加 polyfill 之后才能正常运行,因此设计该 package。在此基础上,README 明确了两条核心设计目标:收敛 pdfjs-dist 调用,避免 bot 环境中多出(多个)定义 pdfjs-dist 版本;收敛 worker src url 的计算逻辑。同时 README 特别标注:该 package 仅供 coze 消费——它不是面向外部发布物的通用组件,而是 Coze 前端 Monorepo 内部的基础设施包,这也解释了它出现在 前端禁用第三方库清单中扮演的白名单替代者角色。pdfjs-dist 本身是 Mozilla 开源的 PDF 解析库,其典型用法包含两个关键动作:一是设置GlobalWorkerOptions.workerSrc指向pdf.worker资源,二是通过getDocument加载文档(可选传入cMapUrl指向字体映射 cmaps 目录)。这两个动作都依赖资源文件的 URL 从哪里来——这正是该包统一收口解决的问题。包结构、构建配置与依赖锁定从源码结构看,该包位于 frontend/packages/arch/pdfjs-shadow 目录下,结构如下:src/index.ts:统一导出入口(API 面);src/init-pdfjs-dist.ts:worker 初始化实现;src/generate-assets.ts:CDN 资源 URL 生成逻辑;src/global.d.ts:全局类型声明;scripts/const.ts:构建输出目录常量;__tests__/:三个 vitest 测试文件。关键构建与元信息集中在 package.json 中,几个字段值得注意:{ name: coze-arch/pdfjs-shadow, main: src/index.ts, unpkg: ./lib, types: ./src/index.ts, files: [lib, README.md], scripts: { build: tsc -b tsconfig.build.json node -r sucrase/register scripts/build.ts, test: vitest --run --passWithNoTests }, devDependencies: { pdfjs-dist: 4.3.136, core-js: ^3.37.1, esbuild: ^0.15.18 }, botPublishConfig: { main: lib/worker.js } }从这些配置可以确认以下事实:pdfjs-dist 版本被锁定在4.3.136,且仅作为该包的 devDependency 存在。配合 devDependencies 中的core-js与esbuild,与 README 中重新编译,增加 polyfill的说法相互印证:polyfill 与重编译发生在该包的构建阶段,消费方拿到的已经是可运行的产物;源码入口src/index.ts直接作为main与types,说明在 Monorepo 开发态下,业务包直接以 TS 源码消费该包,类型链路完整;unpkg: ./lib与files: [lib, README.md]表明发布产物是构建后的lib/目录;botPublishConfig.main指向lib/worker.js,说明构建会产出一个独立的 worker 文件供发布环境使用;scripts/const.ts 中定义了构建输出目录:export const OUTPUT_DIR path.resolve(__dirname, ../lib);即构建产物统一落盘到包根目录下的lib/,与unpkg字段及 CDN 路径约定(见下文)对应。API 面:统一收敛的 pdfjs-dist 调用入口包的完整导出面定义在 src/index.ts:export { getDocument, type PDFDocumentProxy, type PDFPageProxy, type PageViewport, } from pdfjs-dist; export { type TextContent } from pdfjs-dist/types/src/display/text_layer; export { type TextItem } from pdfjs-dist/types/src/display/api; export { generatePdfAssetsUrl } from ./generate-assets; export { initPdfJsWorker } from ./init-pdfjs-dist;这个导出面体现了 README 第一条目标——收敛 pdfjs-dist 调用的具体做法:消费方不再直接import from pdfjs-dist,而是只从coze-arch/pdfjs-shadow导入getDocument、核心类型(PDFDocumentProxy、PDFPageProxy、PageViewport、TextContent、TextItem)以及两个工具函数。pdfjs-dist 的实现细节与版本被完全隔离在这一层之后。这种收敛不只是约定,仓库层面还有强制手段:frontend/disallowed_3rd_libraries.json 中明确登记了[pdfjs-dist, null, 请使用 coze-arch/pdfjs-shadow 代替]即 lint 规则直接禁止业务包依赖裸的 pdfjs-dist,违规引用会被工程链路拦截。这是避免 bot 环境中多出 pdfjs-dist 版本这一目标得以落地的治理保障——无论业务侧多少处用到 PDF 能力,依赖图里只有这一个包持有 pdfjs-dist。仓库中有两类真实消费方可以佐证这一设计:其一,链接预览场景。json-link-preview 的 PDF 预览插件 在模块顶层完成初始化,再调用getDocument加载远程 PDF:import { initPdfJsWorker, getDocument, generatePdfAssetsUrl, type PDFDocumentProxy, } from coze-arch/pdfjs-shadow; initPdfJsWorker(); // ... useEffect(() { getDocument({ url: src, cMapUrl: generatePdfAssetsUrl(cmaps), }) .promise.then(pdf { setPdfDoc(pdf); setPageCount(pdf.numPages); }) // ... }, [src]);这里能看到该包 API 的典型组合:initPdfJsWorker()先执行一次,getDocument传入cMapUrl(即 cmaps 字体映射目录),后续通过pdfDoc.getPage(pageNumber)page.render(...)将页面渲染到canvas上,并处理设备像素比(devicePixelRatio)缩放。其二,知识库文件上传校验场景。knowledge-resource-processor-base 的上传前置校验 采用动态 import,避免 PDF 库进入非 PDF 文件的打包 chunk:const pdfjs await import(coze-arch/pdfjs-shadow); const { getDocument, initPdfJsWorker } pdfjs; initPdfJsWorker(); const uint8Array await getUint8Array(fileInstance); const pdfDocument await getDocument({ data: uint8Array }).promise; if (pdfDocument.numPages PDF_MAX_PAGES) { // 超出页数上限,提示用户并中断上传 }两个消费方均通过workspace:*方式声明依赖(见 knowledge-resource-processor-base/package.json 与 knowledge-resource-processor-core/package.json),进一步确认了版本单一来源。initPdfJsWorker:幂等的 workerSrc 初始化第二个导出函数负责 README 所述收敛 worker src url 的计算逻辑。完整实现见 src/init-pdfjs-dist.ts:import { GlobalWorkerOptions } from pdfjs-dist; import { generatePdfAssetsUrl } from ./generate-assets; /** * This method is used to initialize the workerSrc parameter of pdfjs-dist, which can be called repeatedly */ export const initPdfJsWorker () { if (!GlobalWorkerOptions.workerSrc) { GlobalWorkerOptions.workerSrc generatePdfAssetsUrl(pdf.worker); } };实现上有三个要点:只写不覆盖:仅当GlobalWorkerOptions.workerSrc为空时才赋值。这意味着函数是幂等的,可以在任意模块顶层安全地重复调用(如上面preview.tsx的模块级调用),且不会覆盖调用方或测试环境已显式设置的 worker 地址;URL 计算委托给generatePdfAssetsUrl(pdf.worker):worker 资源地址的计算逻辑完全收口在包内,业务侧无需关心 CDN 域名、版本与区域;注释明确声明可重复调用(can be called repeatedly),这与幂等实现一致。对应测试tests/init-pdfjs-dist.test.ts 用 vitest 的vi.mock模拟pdfjs-dist与generate-assets两个模块,覆盖两条路径:workerSrc 为空时:调用后generatePdfAssetsUrl恰被调用一次且参数为pdf.worker,workerSrc 被设置为生成的 URL;workerSrc 已有值(existing-worker-url)时:再次调用不会触发generatePdfAssetsUrl,原值保持不变。generatePdfAssetsUrl:面向 CDN 的区域化资源寻址worker 地址的来源就是 src/generate-assets.ts,这是整个包中最体现计算逻辑收敛的部分:import pkg from ../package.json; type AssetsType cmaps | pdf.worker; // Here you need to write the version that bnpm has released. const DEFAULT_VERSION 0.1.0-alpha.x6e892414ec; /** * This method is used to produce the worker cmaps link of the unpkg environment. Note that it is not a native method of pdfjs */ export const generatePdfAssetsUrl (assets: AssetsType) { const { name } pkg; let assetsUrl; switch (assets) { case cmaps: { assetsUrl lib/cmaps/; break; } case pdf.worker: { assetsUrl lib/worker.js; break; } default: { throw new Error( 目前只支持引用 cmaps 与 pdf.worker 文件,如需引用其他文件请联系 fanwenjie.fe, ); } } const onlinePkgName name.replace(/^/, ); const domain REGION cn ? lf-cdn.coze.cn/obj/unpkg : sf-cdn.coze.com/obj/unpkg-va; // cp-disable-next-line return //${domain}/${onlinePkgName}/${DEFAULT_VERSION}/${assetsUrl}; }结合tests/generate-assets.test.ts 的用例,可以完整梳理其寻址规则:1. 资源类型白名单(assets)维度。函数签名限定入参为AssetsType cmaps | pdf.worker,分别映射到包内lib/产物中的两个路径:入参映射路径用途cmapslib/cmaps/传给getDocument的cMapUrl,字体映射(字符码映射)文件目录pdf.workerlib/worker.js传给GlobalWorkerOptions.workerSrc,PDF 解析 worker传入其他值会直接抛出错误(目前只支持引用 cmaps 与 pdf.worker 文件),测试中generatePdfAssetsUrl(invalid as any)的断言验证了这一失败路径。白名单化的目的是把哪些文件可以放在 CDN 上被引用控制到最小集。2. 区域(REGION)维度。全局常量REGION决定 CDN 域名(类型见 src/global.d.ts 中的declare const REGION: cn | sg | va):REGIONCDN 域名完整路径示例(pdf.worker)cnlf-cdn.coze.cn/obj/unpkg//lf-cdn.coze.cn/obj/unpkg/coze-arch/pdfjs-shadow/0.1.0-alpha.x6e892414ec/lib/worker.jssg/va(非 cn)sf-cdn.coze.com/obj/unpkg-va//sf-cdn.coze.com/obj/unpkg-va/coze-arch/pdfjs-shadow/0.1.0-alpha.x6e892414ec/lib/worker.js测试用例覆盖了 CN 与va两个区域下 cmaps、worker 共四种组合,均断言了域名、去 scope 后的包名(pkg.name.replace(/^/, ),即coze-arch/pdfjs-shadow→coze-arch/pdfjs-shadow)与资源路径三个要素。注意最终 URL 以//开头(协议相对),协议由页面环境决定。3. 版本维度。DEFAULT_VERSION硬编码为0.1.0-alpha.x6e892414ec,源码注释Here you need to write the version that bnpm has released表明该值需要与该包实际发布到内部 npm 源(bnpm)的版本保持同步——也就是说,CDN 上的资源版本是发布时锁定的,更新 CDN 资源后需要同步修改该常量。这是一个从源码结构看可以推断的运维约束:版本常量、lib/产物与 CDN 上传三者必须一致。全局类型声明:补齐 worker 模块与 REGION 常量src/global.d.ts 提供了三处环境声明,它们解释了上面几个实现细节何以能通过 TS 编译:/// reference typespdfjs-dist / declare module pdfjs-dist/build/pdf.worker.mjs; declare module pdfjs-dist/build/pdf.worker.entry.js; declare const REGION: cn | sg | va;两个declare module为 pdfjs-dist 的 worker 构建产物补上模块类型声明,使构建脚本能够以模块导入方式处理 worker 文件;REGION被声明为编译期注入的全局常量(取值cn | sg | va),运行时由构建/运行环境定义。这也意味着区域寻址不是函数入参,而是部署形态的一部分:同一份代码构建到不同区域环境时,REGION的值决定 CDN 域名;顶部/// reference typespdfjs-dist /引入 pdfjs-dist 的完整类型,支撑src/index.ts中的类型再导出。测试覆盖总览该包在tests目录下维护三个 vitest 测试文件,与 vitest.config.ts 配合执行(npm run test):index.test.ts:验证入口导出面,保证 API 收敛契约稳定;init-pdfjs-dist.test.ts:验证幂等初始化——空值时设置、已有值时不覆盖(见上文引用);generate-assets.test.ts:验证 CN/海外双区域 × cmaps/worker 的资源 URL 生成,以及非法资源类型的异常抛出,并在afterEach中恢复global.REGION。测试对pdfjs-dist与generate-assets均采用vi.mock隔离,保证被测模块行为可断言,这也是一层封装型包应有的测试姿势:不依赖真实 CDN 与真实 pdfjs-dist 运行时。在 Coze 前端工程中使用该包的完整姿势综合源码与真实消费方,在 Monorepo 中接入 PDF 能力的标准流程是:声明 workspace 依赖:在业务包package.json中添加coze-arch/pdfjs-shadow: workspace:*,不要直接依赖pdfjs-dist(会被 disallowed_3rd_libraries.json 的 lint 规则拦截);初始化 worker:在模块顶层或按需调用initPdfJsWorker(),该函数幂等,可放心重复调用;加载文档:import { initPdfJsWorker, getDocument, generatePdfAssetsUrl, } from coze-arch/pdfjs-shadow; initPdfJsWorker(); const pdf await getDocument({ url: pdfUrl, // 远程 URL 场景 // 或 data: uint8Array, // 本地文件/内存数据场景 cMapUrl: generatePdfAssetsUrl(cmaps), // 中文等复杂字形需要 cmaps 支持 }).promise;渲染与翻页:使用pdf.numPages获取页数,pdf.getPage(n)获取页面代理,page.getViewport({ scale })计算视口(通常叠加devicePixelRatio处理高分屏),最终page.render({ canvasContext, viewport, ... })绘制到 canvas;性能考量:对非 PDF 主路径的代码,参考知识库上传校验的实现,使用await import(coze-arch/pdfjs-shadow)动态引入,将 PDF 库排除出首屏主 chunk。小结coze-arch/pdfjs-shadow是一个典型的依赖收敛层设计:它以约两个百行的核心源码(src/index.ts、src/init-pdfjs-dist.ts、src/generate-assets.ts)解决了三个工程问题——pdfjs-dist 版本单一来源(配合 lint 强制规则)、worker 资源 URL 的幂等初始化、以及面向 CN/海外区域的 CDN 资源寻址白名单。对于在 Coze Studio 前端 Monorepo 中新增 PDF 相关功能的开发者,只需记住一件事:一切 PDF 解析入口都从coze-arch/pdfjs-shadow走,而不是pdfjs-dist本身。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
