Node.js cipher.update()教程：增量加密的编码契约、分块限制与流式实践-代码号

一、`cipher.update()`在加密流程中的位置

Node.js的对称加密有两种使用方式：把Cipheriv当作Transform流直接pipe，或者用update()+final()手动分块处理。cipher.update(data[,inputEncoding][,outputEncoding])属于后者。

它接收一段数据，返回截至当前块已加密的内容。对于大多数分组加密算法，可以多次调用update()喂入不同数据块，直到调用final()返回剩余密文并结束本次加密会话。这个设计使得大文件加密不必把整个文件读入内存，而是边读边加密边写出。

const crypto = require('crypto');
const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);

const part1 = cipher.update('第一段数据', 'utf8', 'hex');
const part2 = cipher.update('第二段数据', 'utf8', 'hex');
const tail  = cipher.final('hex');

const encrypted = part1 + part2 + tail;

这段代码的返回值拼接是必须的。update()返回的是截至当前已处理数据中能够输出的部分，final()返回的是剩余未输出的部分。只取update()的返回值或只取final()的返回值，都会得到不完整的密文。StackOverflow上一个经典问题正是源于这个误解：调用方把cipher.update()的返回值当作完整密文使用，忽略了final()。

二、编码契约：两个参数的不对称行为

cipher.update()的两个编码参数在行为上有重要差异，官方文档的措辞需要仔细读。

inputEncoding：如果提供了这个参数，data必须是使用该编码的字符串。如果data已经是Buffer、TypedArray或DataView，inputEncoding会被忽略。这意味着用Buffer喂数据时不需要传这个参数，传了也不影响结果。

outputEncoding：这个参数的约束更严格。如果指定了它，返回的是对应编码的字符串；不指定则返回Buffer。关键规则是：一旦在某次update()调用中指定了outputEncoding，后续所有update()和final()调用都必须使用相同的编码。混用编码会导致不可预期的结果。

// 正确：全程使用 hex 输出
const a = cipher.update('data1', 'utf8', 'hex');
const b = cipher.update('data2', 'utf8', 'hex'); // 一致
const c = cipher.final('hex');                     // 一致

// 有风险的写法：前一次用 hex，后一次不传
const x = cipher.update('data1', 'utf8', 'hex');
const y = cipher.update('data2');                  // 返回 Buffer，拼接时类型不一致

我在代码审查中见过因为中途省略outputEncoding导致密文拼接出现[objectObject]或乱码的情况。根源就是update()返回了Buffer，而调用方用字符串拼接的方式处理它。建议在一个加密会话中，要么全程用字符串编码，要么全程用Buffer，不要中途切换。

三、不是所有加密模式都支持多次`update()`

这是cipher.update()最容易被低估的限制。官方文档明确指出：大多数算法可以多次调用update()，但CCM模式、CBC-CTS模式、XTS模式、AESkeywrap系列模式，以及SIV和GCM-SIV模式要求整个消息在一次调用中传入。

这意味着如果你选了aes-256-gcm（GCM不在限制列表中，可以多次调用），但选了aes-256-ccm，就必须把全部明文准备好一次性update()。流式场景下如果误用了受限模式，会在运行时报错或产生错误密文。

GCM模式还有一个额外要点：认证标签的处理。使用GCM加密后，必须在final()之前或之后通过cipher.getAuthTag()获取认证标签，解密时用decipher.setAuthTag()传入。一个被修复的示例代码曾使用aes-256-gcm做流式加密但没有处理认证标签，导致解密端始终抛出“unabletoauthenticatedata”。如果选择GCM，认证标签的传递和校验不能省略。

四、`final()`不是可选项

cipher.final([outputEncoding])返回加密过程中尚未输出的剩余密文，并结束本次加密会话。调用final()之后，Cipheriv对象不能再用于加密新数据，再次调用final()或update()会抛出错误。

早期Node.js版本中存在一个行为问题：调用update()后如果不调用final()，部分数据不会被输出。社区讨论中有人误以为update()已经返回了全部数据，实际上final()负责的是之后一个分组及其填充的加密输出。对于使用标准块填充的模式（AES-CBC等），final()的输出包含填充处理，跳过它意味着密文不完整。

// 完整的加密流程：update 累积 + final 收尾
function encryptText(plaintext, key, iv) {
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

五、从`createCipher`到`createCipheriv`：为什么本文示例都用后者

crypto.createCipher(algorithm,password)已在Node.jsv10中废弃，原因是它使用不安全的密钥派生方式（直接基于密码生成密钥）。官方推荐使用crypto.createCipheriv(algorithm,key,iv)，由调用方显式提供密钥和初始化向量。

cipher.update()本身在两种构造方式下的调用签名相同，但底层安全性不同。使用createCipheriv时，密钥应通过crypto.scryptSync()或crypto.randomBytes()生成，IV对于CBC模式应是随机且唯一的。输入文章示例中使用了Buffer.alloc(16,0)作为静态IV，这在示例教学中可以展示流程，但在项目中不应使用固定IV——相同明文在相同密钥和固定IV下会产生相同密文，破坏了语义安全性。

六、边界测试与常见错误

以下测试覆盖cipher.update()的核心边界：

const crypto = require('crypto');
const assert = require('assert');

const key = crypto.randomBytes(32);
const iv = crypto.randomBytes(16);

// 边界 1：多次 update 拼接的结果等于一次性 update + final
{
  const c1 = crypto.createCipheriv('aes-256-cbc', key, iv);
  const oneShot = c1.update('hello world', 'utf8', 'hex') + c1.final('hex');

  const c2 = crypto.createCipheriv('aes-256-cbc', key, iv);
  const chunked = c2.update('hello ', 'utf8', 'hex')
                + c2.update('world', 'utf8', 'hex')
                + c2.final('hex');

  assert.strictEqual(oneShot, chunked);
}

// 边界 2：final() 之后调用 update() 抛错
{
  const c = crypto.createCipheriv('aes-256-cbc', key, iv);
  c.update('data');
  c.final();
  assert.throws(() => c.update('more'), /Unsupported state/);
}

// 边界 3：outputEncoding 不一致会返回不同类型
{
  const c = crypto.createCipheriv('aes-256-cbc', key, iv);
  const hexOut = c.update('a', 'utf8', 'hex');
  assert.strictEqual(typeof hexOut, 'string');

  const bufOut = c.update('b'); // 未指定 outputEncoding
  assert.ok(Buffer.isBuffer(bufOut));
}

边界3的结果是update()的合法行为，但返回值类型不一致。实际使用中如果对hexOut和bufOut用同一个变量累积，后续操作会出现类型混乱。这正是前面强调编码一致性的原因。

关于错误码：cipher.update()本身不返回错误码，异常通过throw抛出。常见异常包括：ERR_CRYPTO_INVALID_STATE（在final()后调用update()）、ERR_INVALID_ARG_TYPE（data类型不合法）、ERR_INVALID_ARG_VALUE（编码字符串不合法）。在封装加密工具函数时，建议用try/catch包裹final()调用，因为填充校验失败或认证标签校验失败通常在这一步暴露。

七、常见误区速查

误区一：update()返回的就是完整密文。不是。update()只返回当前能输出的部分，final()必须调用才能获得完整密文。

误区二：所有加密模式都可以流式多次update()。不是。CCM、CBC-CTS、XTS、AESkeywrap系列、SIV/GCM-SIV要求一次传入全部消息。

误区三：outputEncoding每次调用可以随意切换。一旦指定，后续所有update()和final()必须使用相同编码。混用会导致返回类型不一致。

误区四：inputEncoding对Buffer输入有作用。Buffer、TypedArray、DataView作为data时，inputEncoding被忽略。

误区五：GCM模式只需要update+final。GCM还需要在加密端获取认证标签，解密端设置认证标签，否则解密会失败。

八、练习与思考

练习一：写一个函数encryptInChunks(plaintext,key,iv,chunkSize)，将字符串按固定长度切分后逐块调用update()，之后拼接final()。比较结果与一次性update()的密文是否一致。注意chunkSize不需要与AES块大小（16字节）对齐，因为加密会在内部缓冲。

练习二：分别用aes-256-cbc和aes-256-ccm测试多次update()。观察CCM模式下第二次update()的行为，并解释为什么会有不同的结果。

练习三：用aes-256-gcm实现一个完整的加解密往返：加密端调用update()+final()后获取getAuthTag()，解密端在final()之前调用setAuthTag()。故意篡改一个字节的密文，观察final()抛出的错误信息，并设计一个捕获该错误的处理逻辑。

九、延伸阅读与参考文献

Node.js官方文档：cipher.update(data[,inputEncoding][,outputEncoding])
https://nodejs.org/api/crypto.html
编码契约、多次调用限制、final()后调用报错的原始定义。关于CCM、CBC-CTS、XTS、SIV等模式的分块限制，以此处的列举为准。

Node.jsBeta文档：Cipheriv类
https://beta.docs.nodejs.org/crypto/Cipheriv
对Cipheriv作为Transform流与手动update()/final()两种用法的对照说明，以及setAutoPadding()、setAAD()的调用时机约束。

Stack Overflow：Node.js and cryptolibrary
https://stackoverflow.com/questions/4497135
经典问题：调用方只取cipher.update()的返回值而忽略final()，导致解密结果为null。回答明确指出了update()返回值与final()返回值需要拼接。

StackOverflow：Node.jsCryptoAESCipher
https://stackoverflow.com/questions/12067051
早期Node.js版本中update()行为与文档预期不一致的讨论，涉及块大小和自动填充的交互。虽然部分版本问题已修复，但对理解update()与final()的分工仍有参考价值。

GitHub Commit：修复GCM流式加密示例中缺失认证标签的问题
https://github.com/OneUptime/blog/commit/05714022bb0c7219977bd22447104ba6a7f0a4e3
一个实际代码审查案例：使用aes-256-gcm做流式加密但未处理getAuthTag()/setAuthTag()，导致解密始终失败，后改为aes-256-cbc或补充认证标签步骤。对选择加密模式时的考量有直接参考意义。

Definitely Typed：@types/node中crypto.d.ts的update方法签名
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/crypto.d.ts
TypeScript类型定义展示了update()的重载形式，包括string输入与ArrayBufferView输入的分支。在TypeScript项目中编写加密工具时，可据此推断参数类型兼容性。

MDN：Web Crypto API的Subtle Crypto.encrypt()
https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
对照阅读Node.jscipher.update()与WebCryptoAPI的差异：后者通常要求一次性传入完整数据，不支持增量update()。如果项目需要同时兼容浏览器和Node.js，这个差异会影响加密方案的设计。

本文标签：

Node.js cipher.update()教程：增量加密的编码契约、分块限制与流式实践

一、cipher.update()在加密流程中的位置

二、编码契约：两个参数的不对称行为

三、不是所有加密模式都支持多次update()

四、final()不是可选项

五、从createCipher到createCipheriv：为什么本文示例都用后者