SimpleWebAuthn 浏览器端注册流程中的参数传递问题解析

问题背景

在使用SimpleWebAuthn库进行WebAuthn认证时，开发者可能会遇到一个看似简单但容易忽略的问题：在调用startRegistration()方法时，如果参数传递方式不正确，会导致生产环境出现"t is undefined"的错误，而本地开发环境却能正常工作。

问题现象

开发者反馈在生产环境中调用startRegistration(options)时出现以下错误：

• Firefox: "t is undefined"
• Chrome/Safari: "Cannot read properties of undefined (reading 'challenge')"

而在本地开发环境中相同的代码却能正常工作。通过调试发现，options对象中确实包含challenge等必要字段，但在方法调用过程中这些值似乎丢失了。

根本原因

这个问题源于SimpleWebAuthn v11版本的一个重大变更：startRegistration()和startAuthentication()方法的参数传递方式从原来的位置参数改为必须使用命名参数optionsJSON。

在v11之前，可以直接传递options对象：

const registrationResponse = await startRegistration(options);

但在v11之后，必须将options对象作为optionsJSON属性的值传递：

const registrationResponse = await startRegistration({ optionsJSON: options });

解决方案

正确的调用方式有两种：

1. 直接使用命名参数：

const options = await fetchRegistrationOptions(); // 获取注册选项
const registrationResponse = await startRegistration({ optionsJSON: options });

2. 或者在获取选项时将变量命名为optionsJSON：

const optionsJSON = await fetchRegistrationOptions(); // 注意变量名
const registrationResponse = await startRegistration({ optionsJSON });

技术细节

SimpleWebAuthn v11的这一变更主要是为了：

1. 提高API的明确性，通过命名参数使代码意图更清晰
2. 为未来可能的扩展预留空间，可以在同一个对象中添加其他配置项
3. 保持浏览器端和服务器端API风格的一致性

最佳实践

1. 变量命名一致性：建议将获取的注册选项统一命名为optionsJSON，这样在调用时可以直接解构使用。

2. 错误处理：始终对startRegistration()调用进行错误捕获，可以提供更友好的用户提示：

try {
  const registrationResponse = await startRegistration({ optionsJSON: options });
} catch (error) {
  if (error.name === 'InvalidStateError') {
    console.error('认证器可能已被注册');
  } else {
    console.error('注册失败:', error);
  }
}

3. 版本兼容性检查：如果你维护的代码需要支持多个SimpleWebAuthn版本，可以添加版本检测逻辑。

总结

SimpleWebAuthn v11的参数传递方式变更虽然简单，但容易在升级时被忽略。理解这一变更背后的设计意图，并采用一致的变量命名规范，可以避免这类生产环境问题。对于WebAuthn这种安全性要求高的功能，正确使用API不仅能确保功能正常，还能提高代码的可维护性。

对于刚接触WebAuthn的开发者，建议仔细阅读每个版本的变更日志，特别是标记为"Breaking Changes"的部分，以避免类似的升级问题。