Next.js 14.2.6使用argon2遇node:crypto的UnhandledSchemeError解决求助

核心原因 #

argon2是Node.js专属的密码哈希库，依赖node:crypto内置模块，而Webpack默认不解析node:前缀的模块协议；更关键的是，argon2完全不能在浏览器环境运行，如果你的代码在客户端组件中导入了argon2相关逻辑，必然触发报错。

解决方案 #

1. 强制argon2仅在服务器环境执行 #

这是最根本的解决办法，必须确保使用argon2的代码只在服务器端运行：

• 将密码哈希/验证逻辑移至：
  • Server Components（未添加'use client'指令的组件）
  • API Routes（app/api/目录下的路由文件）
  • Server Actions（标记'use server'的异步函数）
• 检查auth.ts是否被客户端组件导入，若有则拆分代码，把argon2相关逻辑单独抽离到服务器端模块。

2. 配置Next.js Webpack处理node:协议模块 #

如果确认代码仅在服务器端运行，但仍报Webpack错误，修改next.config.js添加如下配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (isServer) {
      // 服务器端解析node:前缀模块，直接映射到对应内置模块
      config.resolve.alias = {
        ...config.resolve.alias,
        'node:crypto': 'crypto',
        'node:buffer': 'buffer',
        // 若argon2还依赖其他node:前缀模块，可继续添加
      };
    }
    return config;
  },
};

module.exports = nextConfig;

3. 备选方案：替换为全栈兼容的加密库 #

如果不想调整配置，可改用支持浏览器/Node.js双环境的密码哈希库：

• bcryptjs：纯JS实现的bcrypt，适配全栈场景
• @node-rs/argon2：argon2的Rust绑定版本，对Next.js兼容性更好（无node:前缀导入问题）

额外排查项 #

• 确认NextAuth.js v5的authorize等回调函数中使用argon2是安全的，这些回调默认在服务器端执行
• Node.js 18.x.x已内置crypto模块，无需额外安装依赖

内容的提问来源于stack exchange，提问作者Nardos Tilahun