Node.js 官方 `node:crypto` 实用教程

本教程讲的是 Node.js 官方文档中的 node:crypto 模块，不是 npm 上名称相似的第三方包，也不是只讲抽象密码学概念。

node:crypto 是 Node.js 内置的密码学模块。它不是“把字符串变乱码”的工具箱，而是一组解决不同安全问题的基础能力：

随机生成不可预测的 Token、密钥和盐。
判断数据是否发生变化。
安全保存用户密码。
加密必须在以后恢复的敏感数据。
验证消息是否来自可信的一方。

本教程面向 Node.js 与 TypeScript 初学者，重点是知道“现在遇到的是什么安全问题，应选择哪类工具”，而不是推导 AES、SHA 等算法内部的数学公式。

学习顺序

建议按顺序阅读。第 2～5 章都提供了可以放进当前 TypeScript 项目运行的例子。

一张表先选对工具

实际问题	推荐能力	常用接口	原文能否恢复
生成重置密码 Token	安全随机数	`randomBytes()`	不适用
生成指定范围整数	无偏随机整数	`randomInt()`	不适用
检查文件是否改变	普通哈希	`createHash()`	否
证明消息来自共享密钥持有者	HMAC	`createHmac()`	否
保存用户登录密码	慢速密码哈希	`scrypt()`；生产中也常用 Argon2id	否
保存以后必须取回的密钥或隐私字段	认证加密	`createCipheriv()` / `createDecipheriv()`	是
JWT HS256 签发与验证	HMAC + JWT 规则	实际项目用 `jsonwebtoken`	Payload 本来就可读取
多服务使用私钥签名、公钥验签	非对称签名	`sign()` / `verify()`	不适用

最重要的选择题是：

需要以后得到原文吗？
├── 不需要
│   ├── 人类密码：scrypt / Argon2id
│   ├── 数据指纹：SHA-256
│   └── 还要证明来源：HMAC / 数字签名
└── 需要
    └── AES-GCM 等认证加密

与当前项目的关系

node:crypto 是 Node.js 内置模块，不需要执行 npm install crypto。当前项目采用 TypeScript 源码、CommonJS 编译输出和 ts-node 运行方式，可以直接使用命名导入：

import { createHash, randomBytes } from "node:crypto";

const token = randomBytes(32).toString("base64url");
const digest = createHash("sha256").update(token).digest("hex");

console.log({ token, digest });

保存为临时的 .ts 文件后，可以这样运行：

ts-node 文件名.ts

也可以检查整个项目的 TypeScript 类型：

npx tsc --noEmit

本教程的可运行示例以 Node.js 20 及以上版本为目标，与项目中的 @types/node ^20.11.0 对齐。编写本文时，当前终端实际是 Node.js v12.22.1；它早于本项目的类型声明和部分依赖要求。运行示例前应先切换到 Node.js 20+，否则可能出现“类型检查通过但运行时没有该接口”或依赖无法运行的问题。

Node.js 官方最新版文档还可能列出 crypto.argon2()、randomUUIDv7() 等更新接口。它们是否能用，取决于实际 Node.js 版本、接口稳定级别以及项目的类型声明，不能因为最新版网页存在就直接在旧项目中调用。

学完应该能回答的问题

Base64 为什么不是加密？
SHA-256 为什么适合文件摘要，却不适合直接保存密码？
盐可以公开，为什么每个密码仍然需要不同的盐？
AES-GCM 中 Key、IV、Auth Tag 各自有什么作用？
为什么加密成功不等于数据一定没有被篡改？
JWT 的 Payload 为什么能被读取，签名到底保护了什么？
为什么服务端代码应优先使用异步 scrypt()，而不是 scryptSync()？

如果这些问题都能用自己的话解释，就已经掌握了日常 Node.js 开发中最重要的密码学边界。

主要资料