1. 从一句“能不能做个剧本快读”开始项目缘起与整体设计去年年底一个做短剧的朋友找到我说他们团队每天要处理几十上百个剧本文件格式五花八门——有PDF、有Word、有扫描件甚至还有拍照发过来的。编剧和策划想快速判断一个本子值不值得细看往往得先花十几分钟翻一遍效率极低。他问我“能不能搞个小程序上传剧本自动识别文字再给个快速阅读的摘要”这个需求听起来简单但拆开来看涉及文件上传、OCR文字识别、文本处理、结果展示、用户体系好几个环节。我当时正好在深度使用 WorkBuddy 这个开发工具就想拿它来练手从零做一个能上架的微信小程序。最终成品叫“剧本快读”核心功能就三件事上传剧本文件、自动OCR提取文字、生成可快速浏览的纯文本版本。上线两个月累计用户不算多但整个开发过程踩的坑足够写一篇长文了。这篇文章适合谁看如果你是想用 WorkBuddy 做微信小程序的开发者或者正在规划一个带OCR功能的轻量级工具类小程序再或者你只是好奇“从零到上架”到底要经历哪些环节那这篇记录应该能帮你省下不少时间。我会把整体设计思路、核心技术点、实操步骤、踩坑清单全部摊开讲不藏私。先说整体架构。小程序端用微信原生开发框架没上uniapp原因后面细说。后端用微信云开发云函数负责调用OCR接口和文件处理。OCR这块我对比了几个方案最终选了腾讯云的文字识别服务因为和微信生态打通最顺云函数里直接调SDK就行不用额外维护服务器。数据库用云开发的文档数据库存用户上传记录和识别结果。文件存储用云存储剧本文件上传后生成临时链接云函数拉取后处理。为什么选云开发而不是自建服务器最直接的原因是成本。自建服务器要考虑域名备案、HTTPS证书、负载均衡前期用户量不大的时候纯属浪费。云开发按量计费免费额度对初期完全够用。另一个原因是开发效率云函数里直接拿openid不用自己搞登录态维护省了至少两天的活。当然云开发也有坑比如冷启动延迟、云函数超时限制这些后面会详细说。WorkBuddy 在这个项目里扮演什么角色它更像是一个“全栈工作台”。我可以用它管理整个项目的文件结构快速生成云函数模板调试OCR调用逻辑甚至直接在小程序开发者工具里预览效果。它的缓存目录管理功能帮我省了不少事因为OCR处理过程中会产生大量临时文件手动清理很容易乱。WorkBuddy 的工作台模式让我能把前端代码、云函数、配置文件放在一个视图里切换不用在多个窗口之间反复横跳。提示如果你之前没用过 WorkBuddy建议先花半小时熟悉它的工作台布局和缓存目录设置。默认缓存路径在C盘长期开发建议改到空间更大的盘符否则OCR测试几次就能吃掉好几个G。项目从立项到上架前后大概三周半。其中真正写代码的时间不到一半剩下全花在OCR调优、审核被拒、真机适配这些事上。下面我按模块拆开讲每个环节都会说清楚“为什么这么做”以及“不这么做会怎样”。2. 核心细节解析OCR选型、云函数设计与文件处理2.1 OCR方案对比与最终选择OCR是这个项目的技术核心选型直接决定识别准确率和开发成本。我前后试了四种方案这里把对比结果列出来方便你根据自己项目的情况做判断。方案识别准确率接入难度成本适用场景腾讯云OCR高低按量付费有免费额度微信生态项目首选百度OCR高中按量付费通用场景PaddleOCR自部署中高高服务器成本数据敏感、量大Tesseract本地中中免费简单文档、离线场景我最终选腾讯云OCR理由有三点。第一云函数里直接调SDK不需要额外配置网络代理或签名逻辑代码量最少。第二它对印刷体中文的识别准确率确实高实测剧本PDF转图片后识别率在95%以上。第三免费额度每月1000次对初期用户量完全够用超出后每千次也就几块钱成本可控。PaddleOCR我试过自部署识别效果也不错但需要一台带GPU的服务器或者用CPU跑但速度慢很多。对于一个小程序项目来说维护服务器的心智负担太重。Tesseract免费是免费但中文识别率明显掉一档尤其是剧本里常见的对话格式和特殊标点错得比较多后期校正成本反而更高。注意腾讯云OCR的免费额度是按“接口调用次数”算的不是按文件数。一个多页PDF如果每页都调一次接口消耗会很快。我的做法是先把PDF转成图片再用“多页识别”接口批量处理能省不少调用次数。2.2 云函数架构与超时处理云函数是整个后端逻辑的承载者。我设计了三个云函数uploadFile负责接收小程序上传的文件并存入云存储processOCR负责拉取文件、调用OCR接口、解析结果getResult负责查询识别状态和返回文本。为什么拆成三个而不是一个主要是为了绕开云函数的超时限制。微信云函数默认超时时间是3秒最大可调到60秒。OCR识别一个多页PDF加上文件下载和结果解析很容易超过3秒。拆开之后uploadFile只做上传秒级返回processOCR用异步触发的方式跑不阻塞前端getResult轮询查询状态。这样用户体验上就是“上传后等待几秒到几十秒然后出结果”不会卡在某个环节。processOCR的具体逻辑是这样的先从云存储下载文件到临时目录判断文件类型。如果是PDF用pdf2pic库转成图片序列如果是图片直接进入OCR流程。然后调用腾讯云OCR的GeneralAccurateOCR接口拿到返回的文本块。最后把文本按原始顺序拼接存入数据库更新任务状态为“完成”。这里有个细节PDF转图片时分辨率设置很关键。设太低OCR识别率下降设太高图片体积大上传和识别都慢。我实测下来150 DPI是个平衡点A4纸大小的剧本页转出来大概200KB左右识别率也能接受。如果剧本是扫描件质量本身不高可以适当提到200 DPI但别超过300否则云函数内存容易爆。// processOCR 云函数核心片段 const cloud require(wx-server-sdk) const tencentcloud require(tencentcloud-sdk-nodejs) const OcrClient tencentcloud.ocr.v20181119.Client cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }) exports.main async (event, context) { const { fileID, taskId } event // 下载文件 const res await cloud.downloadFile({ fileID }) const buffer res.fileContent // 判断类型并转换 let images [] if (isPDF(buffer)) { images await pdfToImages(buffer, { dpi: 150 }) } else { images [buffer] } // 调用OCR const client new OcrClient({ credential: { secretId, secretKey }, region: ap-guangzhou }) let fullText for (const img of images) { const ocrRes await client.GeneralAccurateOCR({ ImageBase64: img.toString(base64) }) fullText ocrRes.TextDetections.map(d d.DetectedText).join(\n) } // 存入数据库 await cloud.database().collection(tasks).doc(taskId).update({ data: { status: done, text: fullText } }) }2.3 文件上传与格式兼容处理小程序端上传文件微信提供了wx.chooseMessageFile和wx.chooseMedia两个接口。前者可以从聊天记录里选文件后者只能选相册图片或拍照。剧本文件大多是PDF或Word所以必须用chooseMessageFile。但这里有个坑chooseMessageFile选出来的文件在小程序里只能拿到临时路径需要先调wx.uploadFile传到云存储再拿fileID去调云函数。Word文件的处理更麻烦。云函数里没有现成的库能直接解析.docx我试过用mammoth库但它在Node.js环境里依赖较多打包后云函数体积超限。最后的方案是在小程序端提示用户“建议上传PDF或图片”如果检测到是Word文件先在前端用wx.getFileSystemManager().readFile读成base64再传给一个专门的云函数用officeparser解析。这个方案不算完美但能覆盖大部分场景。实操心得文件上传前一定要做大小限制。微信小程序单次上传文件最大10MB云函数处理时内存上限256MB。我设的限制是PDF不超过8MB图片不超过5MB超过就提示用户压缩或分页上传。这个限制写在文档里能减少很多客诉。3. 实操过程从零搭建到真机调试的完整记录3.1 项目初始化与WorkBuddy工作台配置第一步是在微信开发者工具里创建小程序项目填好AppID选择“不使用云服务”先建空项目。然后手动开通云开发环境拿到环境ID。接着在WorkBuddy里新建工作区把项目目录拖进去。WorkBuddy会自动识别这是微信小程序项目给出对应的文件树和快捷操作。这里重点说WorkBuddy的缓存目录设置。默认情况下WorkBuddy把临时文件、日志、OCR测试产生的图片都放在系统盘的用户目录下。我一开始没注意跑了十几次OCR测试后C盘直接红了。后来在设置里把缓存目录改到D盘的一个专门文件夹问题解决。具体路径在“设置-高级-缓存目录”里改改完重启WorkBuddy生效。# WorkBuddy 缓存目录结构示例改到D盘后 D:\WorkBuddyCache\ ├── temp\ # 临时文件OCR测试图片放这里 ├── logs\ # 运行日志排查云函数调用问题用 ├── projects\ # 项目快照每次保存自动生成 └── ocr_output\ # OCR识别结果缓存方便对比调试项目文件结构我按功能划分miniprogram/放小程序端代码cloudfunctions/放云函数shared/放前后端共用的常量定义。WorkBuddy的工作台可以同时打开这三个目录切换起来很方便。它还支持自定义任务脚本我配了一个“一键部署云函数”的脚本省去了在开发者工具里逐个右键上传的麻烦。3.2 小程序端页面开发与交互设计小程序端一共四个页面首页上传入口、任务列表、结果详情、个人中心。首页设计极简一个大按钮“选择剧本文件”下面一行小字说明支持格式和大小限制。任务列表用scroll-view展示历史记录每条显示文件名、上传时间、状态处理中/已完成/失败。结果详情页用rich-text渲染识别出的文本支持复制和分享。这里有个交互细节值得说上传后不要直接跳转到结果页而是留在当前页显示一个进度条同时轮询任务状态。因为OCR处理需要时间直接跳转过去看到的是空白用户会以为卡死了。我的做法是上传成功后弹一个半屏的“处理中”提示每2秒查一次状态完成后自动跳转。实测这个体验比直接跳转好很多。// 轮询任务状态 async function pollTaskStatus(taskId) { const maxAttempts 30 let attempts 0 const timer setInterval(async () { attempts const res await wx.cloud.callFunction({ name: getResult, data: { taskId } }) if (res.result.status done) { clearInterval(timer) wx.navigateTo({ url: /pages/result/result?id${taskId} }) } else if (attempts maxAttempts) { clearInterval(timer) wx.showToast({ title: 处理超时请重试, icon: none }) } }, 2000) }导航栏高度适配也是个容易忽略的点。微信小程序的顶部导航栏在不同机型上高度不一样尤其是带刘海屏的iPhone和部分安卓机。我用wx.getSystemInfoSync()拿到statusBarHeight和navigationBarHeight动态计算内容区的padding-top。这样在真机上不会出现内容被导航栏遮挡的情况。3.3 云函数部署与OCR接口联调云函数部署在WorkBuddy里可以一键完成但有几个配置项必须手动改。第一是超时时间在云开发控制台把processOCR的超时调到60秒。第二是内存默认256MB处理大PDF时不够我调到了512MB。第三是环境变量把腾讯云的SecretId和SecretKey配进去不要硬编码在代码里。OCR接口联调时遇到一个典型问题本地调试正常真机调用失败。排查后发现是云函数里用的SDK版本和本地不一致。WorkBuddy的本地环境装的是最新版tencentcloud-sdk-nodejs但云函数部署时用的是package.json里锁定的旧版本。解决办法是在package.json里明确指定版本号然后在WorkBuddy里执行“重新安装依赖”再部署。{ dependencies: { wx-server-sdk: ~2.6.3, tencentcloud-sdk-nodejs: ^4.0.500, pdf2pic: ^3.0.0, officeparser: ^4.1.0 } }联调通过后我用WorkBuddy的“批量测试”功能跑了20个不同格式的剧本文件记录每个文件的识别耗时和准确率。测试结果用来优化PDF转图片的DPI参数和OCR接口的调用策略。这个批量测试功能很实用省去了手动一个个上传的麻烦。3.4 上架审核与真机适配小程序上架审核被拒了两次。第一次是因为“服务类目”选错了我选的是“工具-效率”但审核员认为涉及“文字识别”应该选“教育-在线教育”或“商业服务-文印”。后来改到“工具-信息查询”才通过。第二次是因为隐私协议不完整小程序涉及收集用户上传的文件必须在隐私协议里明确说明用途和存储方式。补了一份详细的隐私政策后通过。真机适配方面主要问题是安卓机的文件选择器兼容性。部分安卓机型用wx.chooseMessageFile选出来的文件临时路径在小程序重启后会失效。解决办法是上传成功后立即把fileID存到数据库不要依赖临时路径。另外iOS上rich-text渲染大段文本时会有性能问题超过5000字建议分页加载。避坑技巧提交审核前先用微信开发者工具的“体验版”在至少三台不同机型上跑一遍完整流程。我遇到过华为某机型上云函数调用返回errCode: -1的情况换机测试才发现是网络权限配置问题。4. 常见问题与排查技巧实录4.1 OCR识别率低的排查思路识别率低是最常见的问题原因可能出在文件质量、转换参数、接口选择三个环节。我整理了一个排查流程先看原始文件是否清晰扫描件倾斜或模糊的先做预处理再看PDF转图片的DPI是否合适低于100 DPI基本没法用最后检查OCR接口是否选对腾讯云有GeneralBasicOCR和GeneralAccurateOCR两个接口后者准确率更高但贵一点剧本场景建议直接用后者。如果识别出来文字顺序错乱通常是PDF转图片时页面顺序乱了。pdf2pic库默认按文件名排序但有些PDF内部页码和文件名不一致。解决办法是在转换前先读取PDF的页数按页码顺序生成图片文件名。4.2 云函数超时与内存溢出处理云函数超时一般发生在处理大文件时。除了调大超时时间还可以做分片处理把PDF按页拆成多个小任务每个任务单独调一次云函数。这样单个任务的处理时间短不容易超时。内存溢出则通常是因为一次性把整个PDF加载到内存里改成流式读取或者分页读取能缓解。问题现象可能原因解决方案云函数返回超时文件太大或OCR接口响应慢调大超时时间分片处理内存溢出一次性加载大文件流式读取分页处理OCR返回空结果图片格式不支持或DPI太低转成JPGDPI调到150以上真机调用失败网络权限或SDK版本不一致检查权限配置锁定依赖版本4.3 小程序端常见报错与修复wx.uploadFile报fail file not found通常是临时路径过期了。解决方法是选完文件后立即上传不要等用户点第二次按钮。rich-text渲染乱码检查文本编码是否为UTF-8OCR返回的文本有时会带BOM头需要手动去掉。云函数调用报errCode: -404011一般是环境ID配错了检查cloud.init里的env参数。还有一个隐蔽的坑WorkBuddy的缓存目录如果和微信开发者工具的缓存目录重叠会导致文件锁冲突表现为上传时随机失败。解决办法是把两个工具的缓存目录设到不同盘符或不同父目录下。5. 工具选型与WorkBuddy使用心得5.1 为什么最终选了WorkBuddy而不是纯开发者工具微信开发者工具本身够用但它的文件管理和调试功能比较基础。WorkBuddy的优势在于工作台模式能把项目文件、云函数日志、OCR测试结果放在一个界面里。我特别喜欢它的“任务脚本”功能可以自定义一键部署、一键测试、一键清理缓存省了很多重复操作。另一个实用功能是缓存目录管理。OCR开发过程中会产生大量临时图片和日志手动清理很容易误删项目文件。WorkBuddy可以设置缓存上限超过后自动清理最旧的文件。这个功能在长期开发中很省心。5.2 WorkBuddy缓存目录更改与项目搬迁如果你要把项目从一台机器搬到另一台WorkBuddy的“项目快照”功能很好用。它会打包项目文件、云函数配置、缓存目录设置在新机器上导入后基本能直接跑。但要注意云开发的环境ID和SecretKey不会被打包需要手动重新配置。更改缓存目录的步骤打开WorkBuddy设置找到“高级”选项卡在“缓存目录”一栏选择新路径保存后重启。重启后WorkBuddy会自动把旧缓存迁移到新目录但迁移过程中不要关闭软件否则可能丢文件。提示如果你在Linux上使用WorkBuddy缓存目录默认在~/.workbuddy/cache可以通过修改配置文件里的cacheDir字段来更改。Windows上默认在C:\Users\你的用户名\AppData\Local\WorkBuddy\cache。5.3 从WorkBuddy到上架的完整工具链整个项目用到的工具链其实很简单WorkBuddy负责开发管理和调试微信开发者工具负责预览和上传腾讯云控制台负责云函数配置和OCR额度管理。三者之间的配合关系是WorkBuddy里写代码和调试开发者工具里预览真机效果云控制台里看调用量和账单。有个小技巧在WorkBuddy里配一个“部署前检查”脚本自动检查云函数依赖是否完整、环境变量是否配置、缓存目录是否可写。这个脚本帮我避免了好几次部署后才发现配置遗漏的情况。6. 这个项目后续还能怎么扩展剧本快读目前只做了最基础的OCR提取但可扩展的方向很多。比如加一个“智能摘要”功能用大模型对识别出的文本做摘要直接给出一句话梗概和主要角色列表。再比如加“格式转换”把识别结果导出成TXT或Word方便编剧直接编辑。还可以做“多语言识别”支持英文剧本的OCR。技术层面可以把OCR处理从云函数迁移到云托管解决冷启动和超时问题。数据库可以加索引优化查询速度目前任务列表加载超过50条时会有明显延迟。前端可以用virtual-list优化长列表渲染提升滚动流畅度。我个人在实际操作中的体会是做这类工具类小程序最耗时的不是写代码而是处理各种边界情况和兼容性问题。文件格式、机型差异、审核规则每一项都可能让你卡住半天。但一旦跑通后续迭代就快很多。如果你也在做类似的项目建议先把OCR这条链路跑通再逐步加功能不要一开始就追求大而全。
