垃圾桶边秒查分类：社区垃圾分类查询工具的设计与实现-平芜编程栈

帮住垃圾桶纠偏：我做了个社区垃圾分类指导工具，输入垃圾名直接出分类、时间、投放点

社区里垃圾分类执行了大半年，桶前的督导员撤了之后，准确率肉眼可见往下掉。尤其是早晚高峰，厨余垃圾里混着塑料袋，可回收桶里躺着外卖盒，有害垃圾桶形同虚设。物业贴过彩页，业主群发过分类表，但一张A4纸密密麻麻几十行，真到手上掂着个垃圾袋的时候，没人愿意盯着表格找半天。

所以我做了个小工具，纯网页、免安装、手机打开就能用——输入垃圾名称，自动识别属于可回收、厨余、有害还是其他，附带投放时间、最近的投放点位置，以及一段详细的分类说明，告诉你为什么它是这个分类，还有常见的误放提醒。项目不大，但做完之后社区里反馈挺好，志愿者和保洁员都说比翻表快。

这篇博文把整个项目的需求拆解、分类规则设计、自动匹配原理、完整实操代码和运维避坑全部整理出来。适合社区工作者、物业人员、垃圾分类志愿者，也适合想用最低成本做一个小而美的查询工具的开发者。就算你没有编程基础，照着配置也能跑起来，因为整个工具的核心就是一张词库表加一段轻量级的文本匹配逻辑，没有任何重型框架。

1. 内容整体设计与思路拆解

1.1 核心需求：从“翻表”到“秒查”的体验重构

先重新梳理一下这个工具到底要解决什么问题。表面上，是“输入垃圾名，输出分类”；实际上，是在解决三个层级的矛盾：第一，居民记不住分类规则，尤其是低频率产生的垃圾（旧手机、废灯管、椰子壳），一年也扔不了几次，每次都靠猜；第二，分类表难以覆盖所有垃圾名称的表述差异，同一个东西，有人叫“塑料袋”，有人叫“方便袋”，有人叫“马甲袋”；第三，分类信息只是起点，真正落地还要知道什么时间能扔、扔到哪里，很多小区垃圾桶是定时定点的，时间不对，分类再准也白搭。

所以工具的功能形态必须是“一站式”的：一次查询，返回分类归属、投放时段、投放点位和分类依据说明。这四件事，对应了居民从“这个东西是什么垃圾”到“我现在该去哪扔”的完整决策链。只给分类不给时间地点，工具的价值会打折扣；只给时间地点不给分类说明，居民仍然不理解背后逻辑，下次换个名称还是不会。

这个设计思路本质上是在做“任务闭环”，而不是做“信息孤岛”。很多人做工具喜欢把功能做得大而全，但忽略了用户真正需要的是在最短路径上拿到所有可执行信息。我一开始也想过加拍照识别的功能，后来评估了社区场景下的成本和实用性，果断砍掉了，因为核心矛盾根本不在“识物”，而在“查词”。

1.2 技术选型：为什么是纯前端单页，而不是小程序或App

我最终选择的是纯前端单页HTML + JavaScript + JSON配置文件，整个项目零依赖、零构建、零服务器。这个技术选型不是拍脑袋决定的，而是被社区场景倒逼出来的：

部署成本接近零：社区物业没有专职IT人员，也不会维护服务器。一个HTML文件放进U盘，拷到任何一台电脑上双击就能用；手机端用局域网共享或者生成一个二维码打开同一个页面就行。如果你愿意，甚至可以把它挂到腾讯云或GitHub Pages上，但那是后话。
长期维护成本低：分类规则和投放点位信息是会更新的——比如夏天厨余垃圾破袋检查更严，或者街道重新划了投放点。如果每一次更新都要重新发版、走应用商店审核，这个工具就活不过三个月。用独立的JSON配置文件，物业文员自己打开记事本就能改，改完刷新页面就生效。
隐私和稳定性优先：社区场景下，居民会输入各种垃圾名称，可能包含家庭住址（比如输入“旧空调”后传了楼栋号）、家电品牌等模糊信息。如果走云端接口，数据会经过第三方服务器，既有隐私风险又有稳定性依赖。纯前端本地运行，数据不出设备，断网也能查，这对基层单位的接受度非常关键。

1.3 分类匹配的核心策略：词库+规则，而不是AI模型

很多人一听“自动识别”，第一反应是上大模型或者机器学习分类器，但我从一开始就排除了这个方向。原因很直接：垃圾分类这个场景的查询边界是相对收敛的，一个小区日常产生的垃圾种类大概在几百种以内，高频垃圾就那几十种。用词库+规则匹配，覆盖率能做到95%以上，而且零训练成本、零API调用费用、毫秒级响应。

词库匹配并不是简单的“查字典”，里面有个关键设计：“粗分+细分”的两级判定逻辑。比如输入“电池”，不能直接归入有害垃圾——干电池（碱性电池、碳性电池）在绝大多数城市已经属于其他垃圾了，而纽扣电池、充电电池、铅酸蓄电池属于有害垃圾。这就是分类标准里最常见的坑。词库必须对这类容易混淆的表述做特殊标记，用“命中规则”而不是“命中名称”来兜底。

这个设计的本质，是把“人脑里的分类经验”翻译成“机器可执行的判定逻辑”，规则透明、可解释、可调整。后面我会把词库结构和匹配代码完整展开。

1.4 页面信息架构：怎么让60多岁的大爷一眼看懂

信息架构是这个工具用户体验的核心。普通的查询工具会返回一堆技术参数，但我的页面设计是“结果卡片+大字反馈”的思路：

分类名用超大字号显示，搭配默认的安全色（比如可回收用蓝色、厨余用绿色、有害用红色、其他用灰色），大爷看不清字也能凭颜色反应。
紧随其后的是投放时间和点位，用图标和箭头标识。
最后才是分类说明，默认折叠，想看展开看，不想看也不挡道。

我一直坚信，社区工具的第一原则是“老人友好”。一开始我把所有信息平铺在页面上，测试时发现老人划半天屏幕找不到重点。后来改成“只有一次搜索结果，从上到下按重要性排列”的结构，体验立刻好了很多。工具不是展示技术，而是降低认知负担。

2. 分类规则体系设计：比想象中更复杂的“常识”

2.1 四分类的底层判定逻辑与常见误区

中国的垃圾分类标准整体上是统一的四分类（可回收、厨余、有害、其他），但各地的执行细则有差异，比如上海的“干湿分类”和北京的“厨余垃圾”命名不同，部分城市把“废旧衣物”单列，还有一些城市对“一次性干电池”的规定与国家标准不一致。因此工具设计的第一步，就是确定一个默认标准，同时留出修改入口。

我采用的默认判定逻辑是：

可回收物：适宜回收利用和资源化利用的生活废弃物，重点看材质是否具有再生价值——纸张、塑料、金属、玻璃、织物五大类。
厨余垃圾：易腐烂的、含有机质的生活废弃物，包括剩菜剩饭、瓜皮果核、花卉绿植、肉类碎骨等。注意大骨头、椰子壳、榴莲壳这类“难以生物降解”的，在多数城市归入其他垃圾。
有害垃圾：对人体健康或自然环境造成直接或潜在危害的，分类核心是“含危险成分”——废电池、废灯管、废药品、废油漆及其容器、废含汞温度计等。
其他垃圾：除上述三类之外的，包括受污染的纸张、一次性餐具、尘土、烟蒂、大棒骨等。

这套逻辑本身并不难，难的是居民在实际投放中的“边缘案例”。我把小区里最容易出错的几类整理成了“易错清单”，这是整个工具核心规则设计的原型：

垃圾名称	公众第一直觉	正确分类	分类依据
大棒骨	厨余	其他	质地坚硬难腐蚀，处理设备无法有效破碎
椰子壳	厨余	其他	外壳坚硬，难生物降解
榴莲壳	厨余	其他	外壳坚硬，难生物降解
小龙虾壳	其他	厨余	易腐烂，可生物降解
干电池	有害	其他（多数城市）	低汞或无汞化后按普通垃圾处理
充电电池	其他	有害	含镉、镍等重金属，须专项回收
外卖塑料盒	可回收	其他（未清洗）	含油污残留，回收价值低且污染处理线
旧衣服	可回收	可回收	干净织物可回收；污损严重的属于其他
陶瓷碗	可回收	其他	再生处理成本高，回收利用率低
牛奶盒	可回收	可回收（需压扁）	纸基复合包装，可回收再生

这块规则表不仅是工具的词库基础，本身就可以直接打印出来贴到社区宣传栏上，效果比长篇大论的宣传单好得多。我一直觉得垃圾分类工具的终点不是做一个网页，而是把网页里的规则“翻译”回现实场景里，所以这个表我保留了纯文本导出版本。

2.2 关键词表的分层设计：核心词、特征词、模糊词

词库不是把所有垃圾名称塞进一张表里就行。垃圾名称的构成很复杂，有些是“品类词”，有些是“材质词”，有些是“品牌词+品类词”的组合。为了提升匹配率，我把词库拆成了三个层级：

核心词：唯一指向一种分类的名称，比如“旧报纸”直接命中可回收，“剩饭”直接命中厨余。这类词是词库的主体，覆盖大概70%的查询。
特征词：本身不能决定分类，但和其他词组合后能指向分类，比如“电池”需要结合前缀（“充电”“纽扣”）才能确定；“瓶”需要结合材质（“玻璃瓶”“塑料瓶”）才能确定。特征词会触发模糊匹配规则。
品牌词/型号词：高频出现的产品专名，如“iPhone”旧手机、“戴森吹风机”，这类词单独无法归类，但可以映射到“电子产品”→可回收（或专项回收）。词库维护时，针对小区实际收集到的高频品牌做追加。

这样分层设计的好处是：编辑词库时不需要每一项都精确到全称，只需要维护“哪一层命中+如何处理”的规则即可；查询时如果核心词没命中，再用特征词做二次检索，一层层降级，匹配率会显著提高。

2.3 投放时间与点位的数据模型

投放时间和点位不是简单的文本字符串，而是需要结构化配置的数据。我做了一个简短的数据模型：

投放点：每个点位有“名称”“位置描述”“经度/纬度（可选）”“开放时段数组”。开放时段数组里，每天可以配置多个时段，比如“06:30-08:30”和“18:00-20:00”，支持按周循环。
点位分组：有的小区分为东门点位和南门点位，不同楼栋的居民就近选择不同点位。在结果卡片上，同时返回“匹配到的垃圾名称对应分类的投放点列表”，按楼栋优先级排序。

这个结构在技术上很简单，但在社区实际使用中很重要——我见过不少人拿着“可回收垃圾”分类标准找到可回收桶，结果到点位发现那个桶已经撤了。所以工具的结果里会标注投放点的“当前状态”字段，点位维护人员可以在配置里把已经撤掉的点位标记为“停用”，而不是删掉，这样历史数据不会错乱。

3. 核心代码与数据配置实操

3.1 配置文件的JSON结构示例

整个工具的“大脑”全部集中在一个data.json文件中。数据结构设计如下：

{ "categories": { "recyclable": { "name": "可回收", "color": "#2196F3", "description": "适宜回收利用和资源化利用的生活废弃物，主要包括废纸、塑料、玻璃、金属和废旧织物五大类。投递前请尽量保持清洁干燥，压扁后投放。", "tips": "纸箱请拆开压扁；塑料瓶请倒空残留液体；玻璃瓶请包裹好，避免划伤保洁人员。" }, "kitchen": { "name": "厨余", "color": "#4CAF50", "description": "易腐烂的、含有机质的生活废弃物，包括剩菜剩饭、瓜皮果核、花卉绿植、肉类碎骨等。请沥干水分后破袋投放。", "tips": "大棒骨、椰子壳、榴莲壳属于其他垃圾，不要混入厨余。" }, "hazardous": { "name": "有害", "color": "#F44336", "description": "对人体健康或自然环境造成直接或潜在危害的生活废弃物，包括废电池、废灯管、废药品、废油漆及其容器等。", "tips": "破损的灯管请用厚纸包裹后投放；药品请保留原包装。" }, "other": { "name": "其他", "color": "#9E9E9E", "description": "除可回收物、厨余垃圾、有害垃圾之外的生活废弃物，包括受污染的纸张、一次性餐具、尘土、烟蒂等。", "tips": "一次性干电池（碱性电池）在许多城市属于其他垃圾，可查询本地政策确认。" } }, "garbage_words": [ { "name": "旧报纸", "category": "recyclable", "aliases": ["报纸", "废报纸", "旧报"] }, { "name": "塑料瓶", "category": "recyclable", "aliases": ["矿泉水瓶", "饮料瓶", "塑料空瓶"] }, { "name": "剩饭", "category": "kitchen", "aliases": ["剩菜", "剩菜剩饭", "米饭"] }, { "name": "果皮", "category": "kitchen", "aliases": ["香蕉皮", "苹果皮", "水果皮"] }, { "name": "充电电池", "category": "hazardous", "aliases": ["镍镉电池", "镍氢电池", "锂离子电池", "18650电池"] }, { "name": "纽扣电池", "category": "hazardous", "aliases": ["扣式电池", "手表电池"] }, { "name": "碱性干电池", "category": "other", "aliases": ["5号电池", "7号电池", "AA电池", "AAA电池"] }, { "name": "大棒骨", "category": "other", "aliases": ["猪大骨", "牛骨头", "羊骨头"] }, { "name": "椰子壳", "category": "other", "aliases": [] }, { "name": "外卖盒", "category": "other", "aliases": ["外卖餐盒", "一次性餐盒", "泡沫餐盒"] }, { "name": "陶瓷碗", "category": "other", "aliases": ["陶瓷杯", "瓷砖", "紫砂壶"] } ], "drop_points": [ { "id": "gate_east", "name": "东门投放点", "location": "东门岗亭旁，2号楼对面", "lat": 31.2304, "lng": 121.4737, "status": "active", "schedule": [ { "days": "1,2,3,4,5,6,7", "timeRanges": [["06:30", "08:30"], ["18:00", "20:00"]] } ] } ] }

配置文件里需要特别说明的关键点：

aliases（别名）字段不能省。同一个东西，年轻人说“外卖餐盒”，老年人说“便当盒”，保洁员说“饭盒”，如果没有别名表，就会频繁出现“查不到”。我一开始维护词库时偷懒，结果社区测试阶段不到一周就收集了二十多个别名缺漏，后来索性把补齐别名列为词库更新的第一优先级。
分类的color字段不是装饰。一则方便快速识别，二则在结果卡片里用颜色区分，可以辅助色弱用户。

3.2 核心匹配逻辑：从完整匹配到模糊匹配的降级链

匹配部分的代码逻辑很直观，核心思路是“从精确到模糊、逐级降级”：

第一级：完整匹配——输入的垃圾名称，是否在词库里以“name”或“aliases”精确命中。这一步解决90%的日常查询。
第二级：包含匹配——输入的名称中是否包含词条的关键词。例如用户输入“吃剩的苹果核”，完整匹配失败，但包含“果核”或“苹果”的别名时就能命中厨余。这里要小心，包含匹配会产生误判，所以我会把“苹果核”“香蕉皮”这类词条拆得更细，不让粒度太粗的词参与包含匹配。
第三级：相似度匹配——用编辑距离算法（Levenshtein距离）计算输入与词库中每个词条的相似度，取最高分且超过阈值的结果。阈值我实测下来设0.72比较合适，太低了会频繁把“洗发水”匹配成“洗面奶”，太高了又起不到纠错作用。
第四级：兜底处理——若三级都没命中，不返回“未找到”这种秃头话术，而是返回“未收录该垃圾，建议联系物业确认”，并把用户输入写入一个“待确认日志”，方便后续补充词库。用户查询本身就是在帮系统做标注，这是社区工具最便宜的迭代数据来源。

下面是核心匹配函数的实现片段，直接放在index.html里即可运行：

function levenshteinDistance(a, b) { const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0)); for (let i = 0; i <= a.length; i++) dp[i][0] = i; for (let j = 0; j <= b.length; j++) dp[0][j] = j; for (let i = 1; i <= a.length; i++) { for (let j = 1; j <= b.length; j++) { dp[i][j] = Math.min( dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1) ); } } return dp[a.length][b.length]; } function similarity(a, b) { const maxLen = Math.max(a.length, b.length); if (maxLen === 0) return 1; return 1 - levenshteinDistance(a, b) / maxLen; } function matchGarbage(input, data) { const trimmed = input.trim(); if (!trimmed) return null; // 第一级：完整匹配 for (const item of data.garbage_words) { if (item.name === trimmed || item.aliases.includes(trimmed)) { return { item, method: "exact" }; } } // 第二级：包含匹配（短词不参与，防止误判） if (trimmed.length >= 2 || trimmed.length <= 8) { for (const item of data.garbage_words) { if (item.name.length >= 2 && trimmed.includes(item.name)) { return { item, method: "contains" }; } const hitAlias = item.aliases.find(a => a.length >= 3 && trimmed.includes(a)); if (hitAlias) { return { item, method: "contains_alias", matcher: hitAlias }; } } } // 第三级：相似度匹配 let best = null; let bestScore = 0; for (const item of data.garbage_words) { const score = Math.max(similarity(trimmed, item.name), ...item.aliases.map(a => similarity(trimmed, a))); if (score > bestScore) { bestScore = score; best = item; } } if (best && bestScore >= 0.72) { return { item: best, method: "fuzzy", score: bestScore }; } return null; }

这个函数控制在30行以内，没有任何依赖，但对整个工具来说是最核心的“发动机”。值得一提的是，二级匹配里我加了一个长度限制（只允许词条长度在2~8之间参与包含匹配），这样可以有效规避“一”这类单字误命中。这个限制是实测中总结出来的，不加的话，用户输入“一次性杯子”会被“一次”这个片段干扰。

3.3 界面渲染与时间显示逻辑

界面我用的是原生HTML+CSS，不依赖任何框架。核心结果卡片渲染的逻辑集中在renderResult函数里，逻辑是把匹配到的分类信息、投放点位和当天时间组合在一起：

function renderResult(result, input, data) { const category = data.categories[result.item.category]; const now = new Date(); const today = String(now.getDay()); // 0=周日, 1=周一... let pointHtml = ""; const activePoints = data.drop_points.filter(p => { if (p.status !== "active") return false; return p.schedule.some(s => s.days.split(",").includes(today)); }); activePoints.forEach(p => { const timeRanges = p.schedule .find(s => s.days.split(",").includes(today)) .timeRanges.map(r => `${r[0]}-${r[1]}`) .join("、"); pointHtml += `<div class="point-item">${p.name}（${p.location}）<br>投放时段：${timeRanges}</div>`; }); document.getElementById("result").innerHTML = ` <div class="card" style="border-left: 6px solid ${category.color}"> <div class="category-label" style="color: ${category.color}">${category.name}垃圾</div> <div class="input-word">“${input}”</div> <div class="section-title">分类说明</div> <div class="category-desc">${category.description}</div> <div class="section-title">投放提示</div> <div class="category-tips">${category.tips}</div> <div class="section-title">投放点及时段（按本社区配置）</div> ${pointHtml || "当前没有开放的投放点，请查看社区通知"} </div> `; }

这段代码里有个很容易被忽略的细节：投放点筛选用的是“当天开放”的时段，而不是“本周所有时段”。因为社区的投放时间在周末和工作日往往不同，很多分类查询工具把时间段做成静态文本，一到周末就失效。用now.getDay()动态判断，一天的早8点和晚8点，结果页面上的时段信息始终是准确的，这一点对用户体验的影响比想象中大很多。

3.4 让非技术人员也能维护：配置文件中的注释约定

代码写完了，还有一个很现实的问题——社区物业人员不懂编程，怎么让他们维护词库和点位？

我的解决方案是，在data.json里约定一套“可读注释”规范，用字段名本身说话，不依赖代码注释：

每个词条的"category"字段，只允许写四类枚举值，写错时前端会报红提示。
新增词条时，格式一句话就能说清：“垃圾名:分类；别名用逗号分隔”。
点位状态字段，只用"active"和"inactive"两个枚举。

更进一步，我把data.json放到了在线文档（比如腾讯文档/石墨文档）里维护，物业更新完导出下载，替换掉旧文件即可。整个过程不需要打开编译器，不需要理解JSON语法，只要会打字、会导出就行。这个设计在落地时极其重要——任何需要定期更新的工具，如果更新门槛高于日常能接受的操作成本，这个工具很快就会被弃用。

4. 从零搭建完整工具的操作实录

4.1 目录结构与搭建步骤

整个项目只有三个文件，部署极其简单：

garbage-guide/ ├── index.html # 主页面，含样式、界面和匹配逻辑 ├── data.json # 词库、分类规则、投放点位配置 └── README.txt # 给维护人员的操作说明

搭建步骤如下：

新建文件夹garbage-guide，创建index.html，写入页面骨架、CSS样式和核心匹配代码。
创建data.json，按前面给出的结构填入初始词库。我建议第一天先填入门级词库，大概50条左右覆盖日常最高频的垃圾就够了；之后每周根据“待确认日志”里积累的未收录名称，批量补充一次，两次迭代后覆盖率就能上到90%。
用浏览器打开index.html，确认页面正常渲染，测试几个典型搜索词。
将文件夹拷贝到社区物业电脑，或用局域网共享；如果条件允许，用nginx或者GitHub Pages挂到公网，生成二维码贴到电梯间。

4.2 匹配算法参数如何调优：阈值0.72是怎么来的

相似度匹配的阈值不是拍脑袋定的，而是从社区实际测试数据中算出来的。我在试点初期记录了大约200条真实查询记录，标注了每条查询的期望分类和匹配结果，然后用一套简单的方法排查阈值：

把阈值从0.5逐步上调到0.8，每次上调0.02，记录误判率和漏判率。
发现0.65以下时，误判率明显升高：比如“洗涤灵”和“洗洁精”相似度高达0.79，但分类相同，影响不大；关键问题是“洗面奶”（其他/有害按含有化学成分决定）和“洗洁精”（其他）这种名称相近但分类不同的情况会搞混。
0.75以上时，漏判率显著升高：大量用户口语化的简称（“头绳”“扎带”）变得匹配不到。
0.72左右是误判和漏判的交叉点，最终确定。

这个调优过程再次验证了一点：与其追求模型复杂，不如把数据质量提上去。词库的别名越准确，对模糊匹配的依赖就越低，阈值也可以适当调高，从而减少误判。

4.3 试点数据收集与迭代方案

工具上线后，如何获取查询数据以持续迭代？我在页面里埋了一个极其轻量的统计方案：每次查询如果未命中，就把输入记录到localStorage，并在“维护模式”页面（用隐藏链接，输密码进入）里展示。

实际运行一周后，收集到的未命中记录主要包括三类：

复合名称：比如“用过的口罩”，需要拆成“口罩”+“用过的”，这类词在词库里应该新增“用过的口罩”这一条独立词条，而不是依赖包含匹配。
品牌名词：比如“维达纸巾”“蓝月亮洗衣液”，这类词库只需要记录品牌+品类组合，指向同一个分类。
当地方言俚语：比如某些地区管“一次性餐具”叫“打包盒”或“饭盒”，这些词最需要在试点中收集，因为它们完全依赖本地用词习惯。

这些数据让我认识到，好的词库不是“编”出来的，是“长”出来的。工具上线绝不是结束，而是数据收集的开始。

4.4 投放点位失效与更新：维护流程建议

投放点位存在生命周期：撤桶并点、点位改造、节假日调整、临时封闭。如果工具里的点位信息一两个月不更新，居民会在错误的地方跑空，信任度直接崩盘。

我的建议是建立“双人复核”的更新流程：

点位负责人每月第一周提交点位变更情况，以微信消息或表格形式发给维护人员。
维护人员核对后，更新data.json里对应点位的status字段（在“active”和“inactive”之间切换），并在“location”字段里补一句“因改造临时停用”之类的说明。
更新后，在社区群里发一个简短公告，告诉居民“点位改了，刷新页面即可看到”。

哪怕只是单点更新，这个“双人复核”的习惯也一定要养成——基层工具最大的敌人不是技术难点，而是“数据烂尾”。

5. 常见问题与排查技巧实录

5.1 匹配不到任何结果怎么办

这是最常见的反馈：“查‘泡沫箱’查不到。”每次听到这个问题，我先不急着加词条，而是先确认信息来源是查询时的原始输入，还是居民口语化的转述。因为很多人在手机上输入时会用全拼，输入法可能把“泡沫箱”打成“泡沫相”或“泡沬箱”，相似度阈值又没到0.72，自然匹配不到。

排查路径按优先级排列：

确认输入是否正确，有无错别字。
在data.json里搜索该词条，是否存在但未生效（常见原因是JSON文件里出现了重复键或尾逗号，导致解析失败，整张词库都没加载）。
如果词条不存在，按“先加别名再加主词”的顺序补录。比如“泡沫箱”已有，那再补“泡沫盒”“保温箱”这两个别名。
如果你已经录了但查不到，检查词条是否写在了“aliases”里但没在“name”字段——完整匹配逻辑会先查name，再查aliases，理论上都能查到；但如果JSON格式有误，页面会静默失败。

我在实际操作中还总结了一条铁律：任何匹配不到的记录，必须在当天或第二天补库。拖延一周，记录就丢了，居民也对工具失去耐心。工具刚上线时，我要求自己每天定时看一遍localStorage里的未命中列表，保持“48小时补全”的更新节奏。

5.2 词库更新不生效的排查

物业人员反馈“我改了配置文件，但页面还是老样子”，九成情况是以下原因：

浏览器缓存。解决方案是加一个版本参数，比如在data.json加载时拼接时间戳，让每次刷新都拿最新配置。
JSON语法错误。中文引号和英文引号混用、漏了一个逗号，整个文件解析失败。我会在代码里加一个try/catch，解析失败时在页面顶部弹出一行红字“配置加载失败，请检查data.json”，这样维护者能立刻知道是文件出问题了，而不是傻等。
改了但没重启。如果是通过file://协议打开的，刷新页面即可；如果是通过局域网服务器打开的，注意有些静态服务器会缓存。

这里强烈建议加载配置时用fetch并附加cache: 'no-store'参数：

fetch("data.json", { cache: "no-store" }) .then(res => res.json()) .then(data => { /* 初始化逻辑 */ }) .catch(err => { document.getElementById("config-error").style.display = "block"; });

看起来是一行代码的事，但实际管理运营中能省掉大量“为什么没更新”的来回沟通。

5.3 相似垃圾误判：如何预防高相似度但不同分类的词

这是最难处理的问题，核心是“谐音”或“同名异物”。举个例子：

“玻璃胶”是装修材料，属于其他垃圾（或按有害管理，取决于成分为硅酮类，多数城市归其他）。
“玻璃杯”是可回收物。
“玻璃”和“破玻璃”在投放安全要求上还有不同处理提示。

名称相似、分类不同，包含匹配和相似度匹配都会误伤。这个问题的解决对策，不是提升算法，而是“数据隔离”：把这类高风险的“易混淆对”单独标记，命中检测时碰到底优先走人工确认规则，或者直接返回“请确认具体物品材质后再投放”的提示。

我在词库中增加了一个字段"conflict_group"：

{ "name": "玻璃胶", "category": "other", "conflict_group": "玻璃类" }, { "name": "玻璃杯", "category": "recyclable", "conflict_group": "玻璃类" }

匹配时如果返回的词条有conflict_group，就触发提示“您查询的玻璃胶属于其他垃圾，但玻璃杯等玻璃制品属于可回收物，请对照您手中的实物确认”。这个设计虽然牺牲了一点“完全自动化”，但换来的准确性对社区场景至关重要——因为居民真正需要的是“替我拿主意的确定性”，而不是“看起来智能但模糊的答案”。

5.4 部署到社区后最容易被忽略的细节

工具上线三个月后，我回头复盘，有三件小事特别值得提醒：

字体要够大。社区工具的使用高峰在傍晚扔垃圾的时候，很多人在户外，手机亮度不够，文字必须大。默认渲染尺寸我设置为不小于18px，标题级别用24px以上。
结果页要支持分享。居民查完自己家垃圾，常常会顺手把结果页截图发到家庭群或业主群。这种自发的传播比任何宣传都有效。所以我在结果卡片底部加了一个“复制结果文本”的按钮。
要有“放错提醒”。分类说明里不仅要写“这个是XX垃圾”，还要加一句“注意：XX经常被误放为YY垃圾”。比如“大棒骨”分类提示里写上“经常被误放为厨余垃圾，但它属于其他垃圾”。这个提醒对老人特别管用，因为它直接回应了他们平时的疑虑。

6. 扩展方向：这个工具还能长成什么样

工具跑通之后，我陆续收到一些扩展需求，把我自己觉得有价值的方向列一下，供你参考：

拍照识别：纯前端可以用TensorFlow.js的轻量模型，但社区场景网络环境不稳定，模型文件也大，不优先推荐。如果一定要做，建议用后端OCR（如PaddleOCR）识别+词库匹配，准确率会高很多，但部署成本上去了。
语音输入：微信小程序端可以用语音转文字API，但需要开发小程序，不如纯网页省事。如果社区里有大量不擅长打字的老人，语音输入确实是刚需，可以考虑在现有页面上接浏览器原生Web Speech API，兼容性虽然一般，但零成本。
定时提醒：根据投放点时段，在厨余垃圾投放截止前给居民推送提醒。这是社区工具里最受欢迎的功能，但它需要服务器（或至少一个自动化的消息通道），投入产出比要看社区规模。
多小区复用：把data.json里的点位信息抽成“小区级配置”，工具本身不变，换一套配置就能服务另一个小区。这个扩展最简单，也是我认为最值得做的方向。

我自己最终没有一次性把这些全做完，而是优先把最基础的查询体验打磨稳定。工具这种东西，不求一步到位，关键是跑起来之后有人用、用得惯、愿意反馈，然后根据反馈持续长出新的能力。

做这个项目最大的体会是：技术门槛从来不是社区数字化工具的瓶颈，对用户的理解和持续维护的耐心才是。一个能在垃圾桶边上被大爷大妈真正用起来的工具，比一百个躺在PPT里的智慧社区方案都值钱。