crypto-js 安装与引入：npm 和 CDN 快速上手指南

在前端与 Node.js 开发中，经常需要对敏感数据执行对称加密（如 AES）、生成摘要哈希（如 SHA-256、MD5）或计算接口签名（如 HMAC）。crypto-js 是 JavaScript 生态中被广泛采纳的标准密码学算法库。要使用它，首先需要根据当前项目的技术栈选择合适的引入方式：现代工程化项目首选 npm 安装以实现严格的版本管理与按需加载；而对于快速原型验证、轻量单文件页面或传统无构建项目，通过 CDN 标签引入则是最便捷的途径。本文将针对这两种主流途径，逐一梳理清晰完整的操作步骤与注意事项。

一、通过 npm 安装与工程化引入

使用构建工具（如 Vite、Webpack、Rollup）或编写 Node.js 应用程序时，应当优先使用包管理器将 crypto-js 作为项目的运行时依赖进行安装。这种方式能够获得确定的语义化版本控制，并支持现代 JavaScript 模块规范。

1. 安装依赖包与 TypeScript 类型声明

在项目根目录下打开终端，根据当前项目使用的包管理器执行对应的安装命令：

# 使用 npm 安装运行时依赖
npm install crypto-js

# 使用 yarn 安装
yarn add crypto-js

# 使用 pnpm 安装
pnpm add crypto-js

如果项目使用 TypeScript 进行开发，需要额外安装官方维护的类型定义包 @types/crypto-js 作为开发依赖，否则编辑器会提示找不到类型声明文件：

# 安装类型声明包（推荐开发依赖）
npm install --save-dev @types/crypto-js

2. 代码中的两种引入方式

在代码中引入 crypto-js 时，有两种主要策略：全量引入与按需引入。两者的选择直接影响构建后的最终包体积。

方式 A：全量引入（适合开发调试或多算法混合使用）

在 ES Module 规范下直接导入默认对象，或者在 CommonJS 规范下使用 require：

// ES Module 语法（Vite / Webpack / Vue / React 项目）
import CryptoJS from 'crypto-js';

// 计算 SHA-256 哈希示例
const hash = CryptoJS.SHA256('Hello World').toString();
console.log('SHA256 结果:', hash);

// CommonJS 语法（Node.js 原生环境）
const CryptoJS = require('crypto-js');
const encrypted = CryptoJS.AES.encrypt('秘密内容', 'my-secret-key').toString();

方式 B：按需引入（推荐生产项目使用，减小打包体积）

crypto-js 内部包含大量加密算法标准，打包全量文件通常占用约 400KB 以上源码体积。如果仅需使用 AES 对称加密或 MD5 算法，应直接引用具体的算法子路径，构建工具的 Tree-shaking 即可精准剔除无关算法：

// 仅引入 AES 算法核心与 Utf-8 编码器
import AES from 'crypto-js/aes';
import Utf8 from 'crypto-js/enc-utf8';

// 执行加密
const message = '待加密明文';
const secretKey = 'safe-pass-2026';
const cipherText = AES.encrypt(message, secretKey).toString();

// 执行解密并还原字符串
const bytes = AES.decrypt(cipherText, secretKey);
const originalText = bytes.toString(Utf8);
console.log('解密还原结果:', originalText);

二、通过 CDN 标签直接引入

如果不需要 Webpack、Vite 等构建系统，只是编写独立的 HTML 文件、在教学演示中展示算法、或者在既有传统后端渲染页面（如 JSP、PHP、Django 模板）中临时增加加解密功能，直接使用 <script> 标签从公共 CDN 加载是最直观的方案。

1. 主流公共 CDN 地址选择

可以从以下主流公开 CDN 服务中选取 crypto-js 的压缩版本（crypto-js.min.js）。在实际选择时，请指定明确的版本号以防线上意外漂移：

• cdnjs：https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js
• jsDelivr：https://cdn.jsdelivr.net/npm/crypto-js@4.2.0/crypto-js.min.js
• unpkg：https://unpkg.com/crypto-js@4.2.0/crypto-js.js

2. 完整 HTML 运行示例

当通过 <script> 标签加载 crypto-js.min.js 后，库会自动向浏览器的顶层作用域挂载全局变量 window.CryptoJS。后续脚本必须确保在 CDN 脚本加载完成后执行：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>crypto-js CDN 引入示例</title>
  <!-- 1. 从 CDN 加载完整版 crypto-js -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script>
</head>
<body>
  <h3>加解密测试页面</h3>
  <div id="result"></div>

  <script>
    // 2. 检查全局对象是否成功注入
    if (typeof CryptoJS !== 'undefined') {
      const plainText = '测试明文字符串';
      const key = '1234567890123456'; // 16 字节密钥

      // 计算 MD5 摘要
      const md5Val = CryptoJS.MD5(plainText).toString();

      // 执行 AES 对称加密
      const cipher = CryptoJS.AES.encrypt(plainText, key).toString();

      // 执行 AES 解密
      const decrypted = CryptoJS.AES.decrypt(cipher, key).toString(CryptoJS.enc.Utf8);

      document.getElementById('result').innerHTML = `
        <p><strong>MD5 哈希：</strong> ${md5Val}</p>
        <p><strong>AES 密文：</strong> ${cipher}</p>
        <p><strong>还原明文：</strong> ${decrypted}</p>
      `;
    } else {
      console.error('CryptoJS 尚未正确加载，请检查网络或 CDN 链接！');
    }
  </script>
</body>
</html>

三、npm 与 CDN 选型对比与决策策略

为了让读者在面对具体工程项目时做出最优的技术选型，我们将两种引入方式在网络依赖、构建开销、按需加载、类型支持等关键维度进行直观对比：

四、开发避坑与注意事项

虽然引入 crypto-js 的过程十分直接，但在初次使用时，有几个关于语法规范、类型、输出格式与安全边界的细节极易导致报错：

五、全景总结与速查清单

回顾全文，无论选择哪种引入方式，核心流程都遵循“环境准备 → 引入模块 → 调用算法 → 编码转换”的四步模型。下方的全景速查图为日常开发提供了快速对照索引：

通过本文介绍的步骤，你可以针对不同的应用环境快速完成 crypto-js 的安装与引入。现代模块化工程项目推荐结合 @types/crypto-js 使用子路径按需引入以实现体积优化；而在无需构建流程的场景下，通过固定版本的 CDN 标签可以直接在全局作用域调用全套密码学算法。