1. 从零到上架：为什么我选 WorkBuddy 做「剧本快读」小程序
去年年底，一个做剧本杀发行工作室的朋友找到我，说他们每周要处理上百个剧本的电子版，格式五花八门——PDF、扫描件、手机拍的图片、甚至还有手写稿的翻拍。他们想做一个工具，让玩家和店家能快速把剧本里的文字提取出来，自动分段、标注角色台词，然后生成一个可以按角色筛选阅读的轻量版剧本。需求听起来不复杂，但真正动手做的时候，我发现从零搭建一个微信小程序，光是环境配置、云函数调试、OCR 接口对接这几件事，就够折腾好几天。
后来我用了 WorkBuddy 这个工具来辅助整个开发流程，从项目初始化到代码生成、从云函数调试到真机联调，它帮我省掉了大量重复劳动。最终这个小程序「剧本快读」顺利上架，目前日活稳定在两千左右，主要用户是剧本杀店家和重度玩家。这篇文章就是整个开发过程的完整记录，包括我踩过的坑、绕过的弯路，以及那些文档里不会写的实操细节。
如果你也在做微信小程序，尤其是涉及 OCR 文字识别、云开发、云函数这类功能，或者你正在找一个能提升开发效率的辅助工具，那这篇内容应该能帮你省下不少时间。我会从项目设计思路开始讲，然后拆解核心功能的实现细节，接着是完整的实操流程，最后把我遇到的所有问题整理成一份排查清单。全文没有废话，都是可以直接抄作业的步骤和配置。
2. 项目整体设计与技术选型拆解
2.1 核心需求拆解：剧本快读到底要解决什么问题
先把这个项目的需求说清楚。剧本杀剧本通常有几个特点：篇幅长，一个本子动辄两三万字；角色多，每个角色有独立的视角和台词；格式乱，发行方给的电子版可能是 PDF、Word、扫描图片，甚至微信聊天记录里复制出来的纯文本。玩家的核心痛点是：拿到一个本子，想快速浏览自己角色的台词和关键线索，但翻遍全文太费时间。
所以「剧本快读」的核心功能就三个：第一，把各种格式的剧本文件转成可编辑的纯文本；第二，自动识别并标注角色名和台词；第三，按角色筛选展示，支持快速跳转和搜索。听起来简单，但每个环节都有坑。比如 OCR 识别扫描件的时候，竖排文字、手写体、复杂背景都会导致识别率暴跌；再比如角色名标注，不同剧本的格式差异极大，有的用「角色名：台词」，有的用「【角色名】台词」，还有的干脆没有明确分隔符。
我最终确定的技术方案是：前端用微信小程序原生开发，后端用微信云开发的云函数和云数据库，OCR 部分调用第三方文字识别接口。选原生开发而不是 uni-app 或者 Taro，主要是因为项目功能不复杂，原生开发调试更方便，而且云开发的集成度更高，不需要自己搭服务器。WorkBuddy 在这个过程中主要用来辅助代码生成和调试，尤其是云函数那部分，它帮我自动生成了不少模板代码，省去了查文档的时间。
2.2 为什么选微信云开发而不是自建后端
这个决定其实纠结了很久。自建后端的好处是灵活，想用什么语言、什么数据库都行，但坏处也很明显：要买服务器、配域名、搞 HTTPS 证书、处理并发扩容，对于一个小团队来说，运维成本太高。微信云开发的优势在于开箱即用，云函数、云数据库、云存储、CDN 全都集成好了，而且和小程序的调用链路极短，不需要担心跨域和鉴权问题。
具体到「剧本快读」这个项目，云开发有几个特别实用的点。第一，云函数可以直接读取云存储里的文件，不需要先把文件下载到本地再上传到服务器，省了一次网络传输。第二，云数据库的权限控制可以精细到字段级别，比如剧本内容只有付费用户才能读取，这个用安全规则就能实现，不需要在后端写额外的鉴权逻辑。第三，云开发的免费额度对于初期项目完全够用，等日活上来了再升级付费套餐，成本曲线很平滑。
当然云开发也有坑。比如云函数的冷启动问题，第一次调用可能要等两三秒，用户体验不好。我的解决办法是在小程序启动时先调用一个「预热」云函数，把常用的几个函数提前唤醒。还有就是云数据库的查询限制，单次最多返回 100 条记录，如果剧本角色多的话需要分页处理。这些细节后面会详细讲。
2.3 WorkBuddy 在项目中的角色定位
WorkBuddy 在这个项目里不是替代微信开发者工具，而是作为辅助工具来用。我主要用它做三件事：第一，生成云函数的模板代码，比如 OCR 调用、文件解析、数据库操作这些重复性高的逻辑，它可以直接生成可运行的代码框架，我只需要改改参数就行。第二，调试云函数的时候，它能把日志和错误信息整理得更清晰，尤其是涉及到异步调用和回调嵌套的时候，排查起来比原生日志方便很多。第三，生成一些前端组件的样板代码，比如角色选择器、台词列表、搜索框这些，虽然不复杂，但一个个手写也挺费时间。
需要说明的是，WorkBuddy 生成的代码不能直接拿来就用，尤其是涉及到业务逻辑的部分，必须自己理解和调整。我的做法是把它当成一个「高级代码补全工具」，用它来加速那些标准化程度高的部分，核心业务逻辑还是自己写。这样既能提高效率，又不会因为过度依赖工具而导致代码质量下降。
3. 核心功能实现与实操要点
3.1 OCR 文字识别：从图片到可编辑文本的完整链路
OCR 是这个项目最核心也最容易出问题的环节。剧本文件的来源太杂了，有的是印刷体扫描件，有的是手机拍的屏幕照片，还有的是手写稿翻拍。我测试过好几个 OCR 接口，最后选了一个对中文印刷体识别率较高的第三方服务。整个链路是这样的：用户在小程序里选择文件或拍照，前端把图片上传到云存储，然后调用云函数，云函数从云存储读取图片，调用 OCR 接口，拿到识别结果后做后处理，最后写入云数据库。
这里有几个关键细节。第一，图片上传前要做压缩。微信小程序默认的拍照分辨率很高，一张图可能好几兆，直接上传会很慢。我的做法是用wx.compressImage把图片压缩到 80% 质量，宽度限制在 1600 像素以内，这样既能保证 OCR 识别率，又能把文件大小控制在 500KB 左右。第二，OCR 接口的调用要加超时和重试机制。网络波动或者接口限流都可能导致调用失败，我的云函数里设置了 10 秒超时，失败后自动重试两次，重试间隔分别是 1 秒和 3 秒。第三，识别结果要做清洗。OCR 返回的文本里经常有多余的空格、换行、乱码字符，需要用正则表达式统一处理。
// 云函数中 OCR 调用的核心逻辑 const cloud = require('wx-server-sdk') cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }) exports.main = async (event, context) => { const { fileID } = event const maxRetries = 2 let retryCount = 0 while (retryCount <= maxRetries) { try { // 从云存储下载文件 const res = await cloud.downloadFile({ fileID }) const buffer = res.fileContent // 调用 OCR 接口（此处以通用 HTTP 接口为例） const ocrResult = await callOCRService(buffer) // 清洗识别结果 const cleanedText = cleanOCRText(ocrResult) return { success: true, text: cleanedText } } catch (err) { retryCount++ if (retryCount > maxRetries) { return { success: false, error: err.message } } // 指数退避重试 await sleep(Math.pow(2, retryCount) * 1000) } } } function cleanOCRText(rawText) { return rawText .replace(/\s+/g, ' ') // 合并多余空白 .replace(/[^\u4e00-\u9fa5a-zA-Z0-9，。！？、：；""''（）\s]/g, '') // 去除非文本字符 .replace(/(\d)\s+(\d)/g, '$1$2') // 修复数字间多余空格 .trim() }注意：OCR 接口的调用频率有限制，免费版通常每秒只能调 1-2 次。如果用户一次性上传多张图片，需要在云函数里做队列处理，避免触发限流。
3.2 角色台词自动标注：规则引擎的设计与实现
OCR 出来的文本是一大坨，接下来要做的就是识别出哪些是角色名，哪些是台词。不同剧本的格式差异很大，我统计了手头两百多个剧本样本，发现常见的格式有这几种：角色名：台词、【角色名】台词、角色名（情绪）：台词、角色名\n台词。还有一些剧本用颜色区分角色，但 OCR 出来之后颜色信息就丢了，只能靠文本特征来判断。
我的方案是做一个规则引擎，用正则表达式匹配常见的角色名格式，然后结合上下文做二次校验。具体来说，先定义一组角色名的候选模式，比如「两到四个汉字后面跟冒号」或者「方括号里的两到四个汉字」。然后对每个候选角色名，统计它在全文出现的频率，如果频率太低（比如只出现一次），就可能是误识别，需要排除。最后把识别出的角色名和台词按顺序存入数据库，前端按角色筛选展示。
// 角色名识别的核心规则 const rolePatterns = [ /^([\u4e00-\u9fa5]{2,4})[：:]\s*(.+)$/, // 角色名：台词 /^【([\u4e00-\u9fa5]{2,4})】\s*(.+)$/, // 【角色名】台词 /^([\u4e00-\u9fa5]{2,4})（[^）]*）[：:]\s*(.+)$/ // 角色名（情绪）：台词 ] function extractRoles(text) { const lines = text.split('\n') const roleMap = {} lines.forEach(line => { for (const pattern of rolePatterns) { const match = line.match(pattern) if (match) { const roleName = match[1] const dialogue = match[match.length - 1] if (!roleMap[roleName]) { roleMap[roleName] = { name: roleName, dialogues: [] } } roleMap[roleName].dialogues.push(dialogue) break } } }) // 过滤掉出现次数过少的角色名（可能是误识别） return Object.values(roleMap).filter(role => role.dialogues.length >= 2) }这个规则引擎的准确率大概在 85% 左右，剩下的 15% 需要用户手动修正。所以我在前端做了一个「角色校对」页面，把识别出的角色名列出来，用户可以增删改，也可以手动指定某段文字属于哪个角色。这个页面的交互设计花了不少时间，因为要兼顾易用性和准确性，最后采用的是「左滑删除、右滑编辑」的交互方式，用户反馈还不错。
3.3 云函数与云数据库的配合：数据流转的完整设计
整个项目的数据流是这样的：用户上传文件 → 云存储 → 云函数触发 OCR → 识别结果写入云数据库 → 前端读取数据库展示。这里涉及三个云函数：uploadFile负责接收文件并存入云存储，processOCR负责调用 OCR 接口并清洗数据，saveScript负责把处理好的数据写入数据库。
云数据库的设计上，我建了两个集合：scripts存剧本的基本信息（标题、作者、角色列表、创建时间），dialogues存台词详情（剧本 ID、角色名、台词内容、顺序号）。这样设计的好处是查询灵活，前端可以先查剧本列表，再按剧本 ID 查台词，而且可以根据角色名做筛选。缺点是写入的时候需要两次操作，但云开发的数据库操作很快，用户几乎感知不到延迟。
// saveScript 云函数的核心逻辑 exports.main = async (event, context) => { const { scriptTitle, scriptAuthor, roles } = event const db = cloud.database() // 先写入剧本基本信息 const scriptRes = await db.collection('scripts').add({ data: { title: scriptTitle, author: scriptAuthor, roleCount: roles.length, createTime: db.serverDate() } }) const scriptId = scriptRes._id // 批量写入台词数据 const dialogueTasks = [] roles.forEach(role => { role.dialogues.forEach((dialogue, index) => { dialogueTasks.push( db.collection('dialogues').add({ data: { scriptId, roleName: role.name, content: dialogue, order: index, createTime: db.serverDate() } }) ) }) }) await Promise.all(dialogueTasks) return { success: true, scriptId } }提示：云数据库的批量写入有并发限制，如果台词数量超过 100 条，建议分批写入，每批 50 条，批次之间间隔 100 毫秒。否则可能会触发「请求过于频繁」的错误。
4. 完整实操流程与关键环节记录
4.1 项目初始化与环境配置
第一步是创建小程序项目。在微信开发者工具里新建项目，选择「不使用云服务」还是「使用云服务」？这里一定要选「使用云服务」，因为后面要用到云函数和云数据库。创建完成后，在project.config.json里确认cloudfunctionRoot字段指向了正确的云函数目录。
接下来是配置云开发环境。在开发者工具里点击「云开发」按钮，开通云开发环境，记下环境 ID。然后在app.js里初始化云开发：
// app.js App({ onLaunch() { if (!wx.cloud) { console.error('请使用 2.2.3 或以上的基础库以使用云能力') } else { wx.cloud.init({ env: 'your-env-id', // 替换成你的环境 ID traceUser: true }) } } })WorkBuddy 在这个阶段帮了我不少忙。它的「项目初始化」功能可以自动生成云函数目录结构和基础配置文件，省去了手动创建文件夹和写package.json的时间。不过要注意，它生成的package.json里依赖版本可能不是最新的，建议生成后手动检查一下wx-server-sdk的版本，确保和当前云开发环境兼容。
4.2 文件上传与 OCR 触发的完整实现
文件上传的交互设计上，我提供了两种方式：从聊天记录选择文件和直接拍照。从聊天记录选择文件用wx.chooseMessageFile，拍照用wx.chooseMedia。选完文件后，先压缩再上传到云存储。
// 前端上传文件的逻辑 async function uploadAndProcess() { // 选择文件 const res = await wx.chooseMessageFile({ count: 1, type: 'file', extension: ['pdf', 'doc', 'docx', 'jpg', 'png'] }) const file = res.tempFiles[0] // 如果是图片，先压缩 let filePath = file.path if (file.type.startsWith('image/')) { const compressRes = await wx.compressImage({ src: file.path, quality: 80, compressedWidth: 1600 }) filePath = compressRes.tempFilePath } // 上传到云存储 const uploadRes = await wx.cloud.uploadFile({ cloudPath: `scripts/${Date.now()}-${file.name}`, filePath: filePath }) // 调用云函数处理 OCR const processRes = await wx.cloud.callFunction({ name: 'processOCR', data: { fileID: uploadRes.fileID } }) return processRes.result }这里有个坑要注意：wx.chooseMessageFile选择的文件类型判断。微信返回的file.type有时候不准确，比如 PDF 文件可能返回空字符串。我的做法是同时检查文件扩展名和 MIME 类型，两者取并集来判断。另外，PDF 文件不能直接做 OCR，需要先转成图片。我的方案是在云函数里用pdf-lib或者调用第三方转换服务，把 PDF 的每一页转成图片再做识别。这个转换过程比较耗时，所以我在前端加了进度提示，让用户知道系统正在处理。
4.3 真机调试与性能优化的实操记录
开发阶段在模拟器上跑得好好的，一到真机就出问题，这是微信小程序开发的常态。我遇到的最典型的问题是：模拟器上云函数调用正常，真机上一直超时。排查了半天，发现是手机网络环境的问题——模拟器走的是电脑的网络，而真机走的是移动网络，云函数的调用链路不一样。解决办法是在云函数里增加超时时间，同时在前端加一个「网络检测」的逻辑，如果连续两次调用失败，就提示用户切换网络。
另一个问题是 OCR 识别大文件时的内存溢出。云函数的内存默认是 256MB，处理几十页的 PDF 时很容易爆掉。我的优化方案是分页处理：把 PDF 拆成单页图片，每次只处理一页，处理完一页就把结果存到数据库，然后处理下一页。这样内存占用就降下来了，而且即使中间某一页失败，也不影响已经处理好的部分。
性能优化方面，我做了几件事：第一，把常用的云函数调用结果缓存在小程序的storage里，避免重复请求。第二，云数据库的查询加索引，尤其是scriptId和roleName这两个字段，加了索引之后查询速度提升了将近十倍。第三，前端的台词列表用虚拟列表渲染，只渲染可视区域的内容，避免一次性渲染几千条台词导致卡顿。
5. 常见问题与排查技巧实录
5.1 OCR 识别率低的排查与优化
OCR 识别率低是最常见的问题，原因通常有几种：图片质量差、文字排版复杂、字体特殊。排查的时候，我一般先让用户把原图发给我，用图片查看器放大到 100% 看文字是否清晰。如果原图就不清晰，那 OCR 肯定识别不准，这种情况只能建议用户重新拍摄或扫描。
如果原图清晰但识别率还是低，那可能是排版问题。比如竖排文字、多栏排版、文字和背景对比度低，这些都会影响识别。我的处理方案是在 OCR 之前先做图像预处理：用sharp库做灰度化、二值化、去噪，提高文字和背景的对比度。这个预处理步骤在云函数里做，大概增加 200-300 毫秒的处理时间，但识别率能提升 15% 左右。
还有一个容易被忽略的点是 OCR 接口的语言模型选择。有些接口默认用的是通用模型，对特定领域的文本识别率不高。比如剧本里经常出现生僻字、古风词汇，通用模型可能识别不出来。我的做法是收集一批识别错误的样本，反馈给 OCR 服务商，让他们针对性地优化模型。这个过程比较漫长，但效果是长期的。
5.2 云函数超时与冷启动的解决思路
云函数超时通常发生在处理大文件的时候。微信云函数的默认超时时间是 3 秒，最长可以设置到 60 秒。我的processOCR函数设置了 30 秒超时，因为 OCR 接口本身可能就要 5-10 秒，加上文件下载和结果清洗，30 秒是比较保险的。
冷启动问题更麻烦。云函数在一段时间没有调用后会被回收，下次调用时需要重新初始化，这个过程可能持续 2-3 秒。对于用户体验来说，这个延迟很明显。我的解决方案是在小程序启动时调用一个「预热」函数，这个函数什么都不做，只是把云函数的实例唤醒。具体做法是在app.js的onLaunch里调用一个空的云函数：
// 预热云函数，减少冷启动延迟 wx.cloud.callFunction({ name: 'warmup', data: {} }).catch(() => {})这个技巧实测有效，冷启动延迟从平均 2.5 秒降到了 0.8 秒左右。不过要注意，预热函数本身也会消耗云函数的调用次数，如果项目对成本敏感，可以只在用户打开小程序时预热一次，不要频繁调用。
5.3 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| OCR 识别结果为空 | 图片格式不支持或文件损坏 | 检查文件扩展名和 MIME 类型 | 转换文件格式后重试 |
| 云函数调用超时 | 文件过大或网络延迟 | 查看云函数日志中的耗时 | 增加超时时间，分页处理 |
| 真机接口访问失败 | 网络环境差异或域名未配置 | 对比模拟器和真机的网络请求 | 检查云开发环境 ID 和网络权限 |
| 数据库查询返回空 | 权限设置或索引缺失 | 检查数据库安全规则和索引 | 调整权限，添加查询索引 |
| 台词列表卡顿 | 一次性渲染数据过多 | 查看页面渲染耗时 | 使用虚拟列表，分页加载 |
| 角色名识别错误 | 格式不匹配或误识别 | 检查正则表达式匹配结果 | 增加规则，手动校对 |
注意：云函数的日志在微信开发者工具的「云开发」控制台里查看，真机上的错误日志需要在小程序管理后台的「运维中心」里看。两个地方的日志格式不一样，排查的时候要结合起来看。
5.4 上架审核的避坑经验
小程序上架审核有几个容易踩的坑。第一，类目选择。剧本快读这个功能，我一开始选的是「工具-效率」，被驳回了，理由是涉及「内容阅读」需要补充「文娱-资讯」类目。后来改成「文娱-资讯」才通过。第二，用户隐私协议。小程序涉及收集用户上传的文件，必须在隐私协议里明确说明数据的用途和存储方式。第三，内容安全。用户上传的剧本内容需要做审核，防止出现违规内容。我的做法是接入微信的内容安全接口，对 OCR 出来的文本做敏感词过滤，发现违规内容自动拦截并提示用户。
审核周期一般是 1-3 个工作日，如果被驳回，修改后重新提交即可。我的经验是，第一次提交的时候尽量把类目、隐私协议、内容安全都做完整，避免反复修改浪费时间。
6. 一些实操心得与后续扩展思路
这个项目从立项到上架大概用了三周时间，其中 OCR 调优和真机调试占了一半以上的时间。WorkBuddy 在代码生成和调试辅助上确实帮了不少忙，尤其是云函数那部分，它生成的模板代码让我少查了很多文档。但它也不是万能的，涉及到业务逻辑和性能优化的部分，还是得自己动手。
有几个小技巧我觉得挺实用。第一，云函数的日志里加一个requestId，每次调用生成一个唯一标识，这样排查问题的时候可以把相关的日志串起来看。第二，前端的错误提示要具体，不要只说「操作失败」，要告诉用户失败的原因和下一步该怎么做。第三，数据库的字段命名要统一，我一开始用了scriptId和script_id两种写法，后来统一成驼峰命名，维护起来方便很多。
后续我打算加两个功能：一个是「角色语音朗读」，用微信的语音合成接口把台词读出来，方便玩家在走路或者做家务的时候「听剧本」；另一个是「剧本对比」，把同一角色的不同版本台词并列展示，方便店家做版本校对。这两个功能的技术方案还在调研中，等做出来了再写一篇记录。
如果你也在做类似的小程序，或者对 OCR 和云开发有疑问，欢迎交流。踩过的坑我都写在上面了，希望能帮你少走点弯路。
