做开发这些年，MD5 大概是碰得最频繁的“加密”工具之一。测接口签名、校验文件完整性、给测试数据造个定长指纹，随手就是一个 md5()。但真正要把这东西做成一个能上线的工具，尤其是用 Vue 3 和 TypeScript 从零写一个带“加密/解密”能力的在线页面，里面牵扯到的概念梳理、算法边界、工程实现坑点，远比想象中多。这篇文章就把完整思路、核心代码和实测中踩过的坑都摆出来，给正准备做类似小工具或者想搞清楚 MD5 到底是什么的朋友做个参考。

这项目要解决的痛点其实很直白：本地要算个 MD5，要么开终端敲命令，要么去某些广告满天飞的在线站，粘一段文本还得担心它会不会被偷偷记录。自己做一个小工具，数据不出浏览器，既能算 MD5、又能反向查常见明文，顺便支持定时“解密”和文件校验，日常开发调试完全够用。适合前端入门想练 Vue 3 组合式 API 的同学，也适合后端同学想搞个趁手的小页面。

1. 项目概述：MD5 工具到底解决了什么问题

1.1 先纠正一个概念：MD5 不是加密，是散列

项目标题里写的是“MD5 加密/解密”，但严格来说，MD5 是消息摘要算法，属于散列函数，不是加密算法。这两者的本质区别在于：加密是可逆的，密文可以还原成明文；散列是不可逆的，无论输入多长，输出固定 32 位十六进制字符，而且理论上无法从这 32 位字符反推出原始输入。

这个区别决定了整个工具的设计基调。如果你真的实现一个函数，想对 MD5 后的结果做“解密”，那是不可能的。所谓“在线 MD5 解密”，本质上是碰撞查询：先准备一个大字典，把常见明文（弱密码、默认值、测试串）预先算好 MD5，再把用户输入拿去比对。匹配上了，就“解密”成功；匹配不上，就返回空。

所以这款工具真正的核心是两部分：正向的 MD5 计算，和反向的字典碰撞查询。搞清楚这一点，后面所有设计都不会跑偏。

1.2 为什么还需要“解密”功能

很多人会问：MD5 既然不可逆，那做“解密”功能有什么意义？实际开发中的价值非常大。

比如你在排查历史遗留系统，数据库里存的密码是 MD5，但是明文规则丢了，看不到原始值。你拿一串 MD5 丢到工具里，如果能查到明文，等于在没有业务代码介入的情况下找到了线索。再比如测试环境里有些加密配置项，对方给的是 MD5 值，你想验证一下当前输入的配置是否匹配，直接反向查一下比对着算方便得多。

当然需要清醒地知道：这种查询只能命中预先收录的字典。弱密码如 “123456”、“admin888” 基本一查一个准，你随便编的一段十几位数的随机字符串，查不到就是查不到。

1.3 技术选型：为什么是 Vue 3 + TypeScript

选 Vue 3 是因为组合式 API（Composition API）非常适合这种“单一功能、多交互入口”的页面。加密、解密、批量处理、文件校验，本质上都是围绕同一个核心算法展开的，用 setup 函数 + 自定义 composable 可以把逻辑拆得非常干净，比 Options API 写起来顺手太多。

TypeScript 则是给这个项目兜底的关键。MD5 的核心处理涉及字节数组、十六进制转换、补位长度计算，这些地方最容易出现类型陷阱（比如把 number 当成 string 拼接，或者 buffer 下标越界）。有类型检查在编译期拦住一批低级错误，省下来的调试时间远超写类型标注花的功夫。

构建工具用 Vite，开发环境秒级热更新，打出来包也小，部署到静态服务器或者内网 NAS 上都很方便。

2. MD5 算法拆解与在线“解密”的真实机制

2.1 MD5 的计算流程，用大白话讲清楚

MD5 的算法流程不算复杂，核心是四个步骤：

• 填充：让原始数据字节数对 512 取模等于 448，不足则补位，先补一个 0x80，再补一堆 0x00。
• 追加长度：在填充后的数据末尾追加 64 位的原始长度信息。
• 分组处理：把数据按照 512 位（64 字节）分块，每块拆成 16 个 32 位字。
• 四轮运算：初始向量是 A、B、C、D 四个 32 位常数，每一轮用非线性函数（F、G、H、I）对当前块做 16 次运算，不断更新 A、B、C、D，最后拼接输出。

文字描述比较干瘪，实际写代码时你不需要从零去手写这些运算，直接使用现成的库即可。但如果想把它作为学习素材，亲手写一遍对理解散列函数非常有帮助。我在项目里就用了一个轻量的第三方实现，不过封装层是自己写的，方便控制输入输出格式。

但这里要提醒一个常见误区：很多小白以为 MD5 输出是一串字符串，其实算法中间全是二进制运算。你在页面上看到的 “e10adc3949ba59abbe56e057f20f883e”，是最终哈希值按字节转十六进制后的展示形态。输入同一个字符串，编码方式不一样，结果完全不同。UTF-8 的 “abc” 和 GBK 的 “abc” 算出来的 MD5 是不一致的，这是第一个高频坑。

2.2 所谓“解密”的三种真实路径

在线 MD5 “解密”主要有三条实现路径：

第一条是彩虹表，也叫预计算哈希链。把大量明文通过算法生成对应哈希链，存储时只保留端点，查询时通过链式推导还原。彩虹表的特点是存储空间比完整字典小很多，适合超大规模的碰撞查询。

第二条是普通字典查询。直接把常见明文和对应 MD5 存在数据库里，查询 O(1)，实现最简单。我这个小工具用的是这个方案，内置了一个几十万条的高频密码字典，覆盖常见的弱口令、数字串、单词变体和部分默认测试值。

第三条是暴力枚举。针对短字符串（4 到 8 位纯数字）做全排列匹配，只要算力够，基本都能跑出来。这个工具里也加了枚举模式，不过限制了位数，防止浏览器卡死。

用户端的“解密”逻辑很简单：输入一个 32 位 MD5，先在本地字典里查；查不到就发到后端接口查更大规模的库；再不行就启动枚举线程尝试。整个过程对用户是透明的，你只需要看结果。

2.3 安全性讨论：什么时候能用，什么时候绝对不能用

MD5 的安全性在现代密码学语境下已经基本宣判死刑。2017 年之后，阻止 MD5 碰撞攻击已经不算难事，安全合规项目里如果再拿 MD5 做密码存储，评审那一关基本过不去。所以这篇工具的使用场景一定要限定在：

• 数据完整性校验，比如下载文件后比对 MD5，确认传输过程没篡改。
• 接口签名中的参与值计算，很多老系统的签名规范里会用到 MD5。
• 测试数据的指纹生成，方便定位和对比。
• 非敏感数据的指纹标记，比如查重。

绝不能在以下场景使用：

• 用户密码存储，需要改用 bcrypt、scrypt、Argon2 这类专门设计的密码哈希算法。
• 高安全等级的数据加密，需要改用 AES、RSA 等对称或非对称加密。
• 任何需要防抵赖的电子签名场景。

这个工具本身是无害的，它只是如实执行了算法逻辑。“哪些用途合法、哪些用途业内有共识不能碰”，这需要使用者自己判断。

3. 功能设计与实现思路

3.1 功能清单与优先级划分

项目从立项到可用，我规划了以下功能模块，按优先级排序：

• MD5 计算（核心）：输入文本，输出 32 位小写哈希，支持切换大写。
• 文件 MD5 校验：拖拽或选择文件，计算文件流哈希，用于传输校验。
• 在线反查（解密）：内置高频字典，点击后返回匹配明文。
• 批量模式：每行一条文本，分别计算哈希并输出表格，支持复制。
• 环境辅助：一键复制结果、清空输入、暗色模式。

每个功能都不花哨，但组合起来就是一个完整的开发辅助工具。设计上遵循一个原则：所有计算优先在浏览器本地完成，只有反查字典这种本地搞不定的才走后端接口。这样部署成本极低，隐私也有保障。

3.2 核心计算层：为什么我选择自己封装而不是直接调页面

市面上有不少现成的 JS 库，浏览器端也很流行引入 SparkMD5 或者 js-md5。这个项目我一开始直接引了 js-md5，但用着用着发现问题：文件校验时，需要将 ArrayBuffer 转换成二进制字符串再交给库处理，文件一大会卡顿。另外我需要同时控制 UTF-8 中文字符串的编码方式，直接调库有时无法保证浏览器行为和 Node 端完全一致。

所以后来我做了一层薄的封装，核心 md5() 函数仍然是第三方库的实现，但外层统一做编码归一化、Hex 输出大小写控制、ArrayBuffer 输入适配。这样页面调用时只需要传字符串或 buffer，不需要关心内部细节。这也算一个工程结论：引入依赖没毛病，但要在依赖之上加一层服务于本项目的胶水代码。

3.3 交互细节与易用性设计

工具类页面最忌讳功能全堆在页面上，用户一进来不知道干什么。设计上按场景划分功能区：默认显示的是“文本计算”，用户输入内容，实时显示 MD5 值；旁边一个 Tab 放“文件校验”，拖拽文件进去自动计算；反查功能做成一个单独的按钮，在拿到 MD5 后点击才执行。这样入口清晰，屏蔽了不少无谓的复杂度。

实时计算这里有个性能细节：监听输入事件后每敲一个字符都重算一遍，小的文本没问题，如果粘贴一篇长文就会明显卡顿。所以引入了防抖处理，300ms 延迟，并且加了requestIdleCallback兜底，保证在输入框失去焦点时计算结果最终会刷新。

复制结果按钮虽然简单，但里面用了navigator.clipboard.writeText，需要页面在 HTTPS 或者 localhost 下才能正常工作。本地调试没感觉，部署到纯 HTTP 内网环境时按钮会失效，这是我实测踩过的一个坑，后面排查章节细说。

4. 编码实现与实操记录

4.1 项目初始化与环境准备

环境要求很简单，Node.js 18+ 即可，包管理器用的 pnpm。初始化命令：

pnpm create vite md5-tool --template vue-ts cd md5-tool pnpm install

装完依赖后，把目录结构调整成这样：

src/ core/ # 算法封装层 md5.ts lookup.ts # 字典查询 composables/ useMd5.ts # 计算逻辑 useFileHash.ts # 文件校验 views/ Home.vue

核心思路是把纯函数（算法、查询）和状态逻辑（composable）分离。md5.ts不依赖 Vue，useMd5.ts负责响应式状态和业务编排。这样单元测试也好写，后续换 UI 框架也不心疼。

4.2 核心代码实现

md5.ts里最关键的是封装一个统一的输入解析函数：

import md5Lib from 'js-md5'; export type Md5Input = string | ArrayBuffer | Uint8Array; export function computeMd5(input: Md5Input, uppercase = false): string { let result = ''; if (typeof input === 'string') { // 统一按 UTF-8 处理 result = md5Lib(input, { asBytes: false }) as string; } else { // ArrayBuffer / Uint8Array 走 Buffer 路径 result = md5Lib(new Uint8Array(input as ArrayBuffer)) as string; } return uppercase ? result.toUpperCase() : result.toLowerCase(); }

字典查询核心逻辑，用的是二分查找优化，因为插入字典时是排序好的：

export interface LookupEntry { hash: string; plain: string; } export function lookupHash(target: string, dict: LookupEntry[]): string | null { const lower = target.toLowerCase(); let left = 0; let right = dict.length - 1; while (left <= right) { const mid = Math.floor((left + right) / 2); if (dict[mid].hash === lower) { return dict[mid].plain; } else if (dict[mid].hash < lower) { left = mid + 1; } else { right = mid - 1; } } return null; }

不过实际项目中我并没有把整个字典一次性加载到内存，而是做成了按需请求：状态中维护一个dictStatus，如果用户第一次点击反查，再从/dict/dict.json.gz加载，解压后缓存到全局。这样首屏体积能控制住，字典还能持续更新。

4.3 踩坑记录：中文编码、文件处理与性能优化

第一个坑是中文编码。js-md5对纯 ASCII 字符串没问题，对中文字符串，内部默认按 UTF-8 处理。但坑在于，浏览器端有的环境默认按 UTF-8，有的跑了 polyfill 之后行为会变。解决方式是拿到文本后显式执行一次：

const encoder = new TextEncoder(); const data = encoder.encode(input); const result = md5Lib(data);

这样处理之后，无论什么环境，结果都是同样的 UTF-8 语义，跨端不会对不上。

第二个坑是文件校验的内存问题。早期版本把整个文件读成字符串再交给库，500MB 的文件直接浏览器崩溃。后来改成分块读取：

async function hashFile(file: File, chunkSize = 2 * 1024 * 1024) { const buffer = await file.arrayBuffer(); const totalChunks = Math.ceil(buffer.byteLength / chunkSize); // 一些实现需要多次 update 才能得到最终哈希 const md5 = md5Lib.create(); for (let i = 0; i < totalChunks; i++) { const chunk = buffer.slice(i * chunkSize, (i + 1) * chunkSize); md5.update(new Uint8Array(chunk)); } return md5.hex(); }

这里注意一个大文件易踩的坑：file.arrayBuffer()会一次性把整个文件读入内存，还是可能爆内存。真要做大文件支持，应该用file.stream()读取，实际上我用的是ReadableStream配合逐步读取。为了篇幅这里只保留了分块逻辑，但结论是：文件校验功能是有技术门槛的，不是简单拼接一下就能上。

第三个坑是渲染大数据量的卡顿。批量模式下如果一次算 1000 行文本，DOM 渲染 1000 行表格会明显掉帧。方案是把表格虚拟滚动化，用的是vitest写轻量组件，把渲染窗口控制在 20 行以内。测试下来几千行数据滚动依然流畅。

5. 构建部署与常见问题排查

5.1 构建配置与部署细节

Vite 的构建配置基本不用动，唯一要注意的是base字段。如果部署在域名根目录，默认/没问题；如果是部署到子路径（内网服务常见），就必须设置：

export default defineConfig({ base: '/md5-tool/', // 对应部署路径 build: { target: 'es2020', chunkSizeWarningLimit: 1500, }, });

不设置base的话，打包出的 JS 和 CSS 路径全是/assets/xxx.js，部署到子目录后页面一片空白，控制台全是 404，这是部署类项目最常见的坑。

另外，因为用到了 Web Worker 跑字典查询，worker 文件打包有自己的细节。Vite 推荐的写法是通过new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })来引入，这样打包器能正确识别并拆分 worker chunk。如果直接把 worker 代码当普通字符串塞进去，闭包变量会被压缩到面目全非，部署之后功能直接失效。

5.2 在线 MD5 工具的常见问题速查表

5.3 后续扩展方向

工具的基础版本已经可以投入使用，后续值得做的扩展还有几个方向：

• 支持更多哈希算法：SHA-1、SHA-256、SHA-512 是自然的增量，算法细节类似，代码抽象好后加算法策略枚举就能实现。
• 自定义盐值模式：把 MD5、SHA-256 跟固定的盐拼接后重新计算，这对某些老系统的密码迁移很有用。
• 导出碰撞字典：把反查功能做成本地数据库导出，方便离线环境使用。
• 自动检测输入类型：传入明文就当作加密算哈希，传入 32 位十六进制串就优先尝试反查，减少用户理解成本。

这些扩展并不复杂，但每一步都能把工具从“小而美”推向“团队内网亲测好用的工程利器”。

写在最后

这个项目做完，我自己最大的体会是——工具虽小，但概念一定要拎清。MD5 在开发链路里太常见了，常见到很多人已经忘记它到底是个加密算法还是个散列算法。它做不了真正的解密，但通过字典查询可以在合理的范围内提供辅助能力。它不具备高安全性，但在文件校验、请求签名这类场景里依然老当益壮。

如果你准备自己写一个同类工具，建议优先梳理清楚使用边界，再把交互打磨顺手。功能未必多，但用起来要让人感觉“明显比打开终端敲命令和访问那些满屏广告的站靠谱”。这样的工具，自己用着舒心，分享给同事也有价值。

另外提一个小建议，工具的字典数据记得做版本管理和合规审查，毕竟内置弱口令库这种能力，用得好是效率工具，被人拿去搞歪门邪道就是另一回事了。控制好能力和边界，是做工具的人该有的自觉。