Valibot 库中 `@__NO_SIDE_EFFECTS__` 注解引发的构建优化问题分析

问题背景

Valibot 是一个用于数据验证的 JavaScript 库。在最新版本中，开发者发现了一个与构建工具优化相关的重要问题：当使用 parse 函数进行数据验证时，某些调用在最终的生产构建中被意外移除了。

问题现象

开发者在使用 Valibot 的 parse 函数时，发现以下三种调用方式在构建后的表现不一致：

1. 直接调用 parse 函数但不使用返回值
2. 将 parse 结果赋值给变量但不使用
3. 在 console.log 中直接使用 parse 结果

构建后，只有第三种方式（在 console.log 中使用）的调用被保留下来，前两种调用都被构建工具移除了。

根本原因

这个问题源于 Valibot 代码中对 parse 函数使用了 @__NO_SIDE_EFFECTS__ 注解。这个注解告诉构建工具（如 Rollup、Vite 等）该函数是纯函数，没有副作用，可以安全地进行移除。

然而，parse 函数实际上是有副作用的 - 当验证失败时会抛出异常。抛出异常是一种明显的副作用行为，不应该被标记为无副作用函数。构建工具基于这个错误的注解，移除了它认为"无用"的函数调用。

技术细节

副作用的概念

在函数式编程中，纯函数是指：

• 相同的输入总是产生相同的输出
• 不会产生任何可观察的副作用

副作用包括但不限于：

• 修改外部状态
• 抛出异常
• 进行 I/O 操作
• 修改 DOM

构建工具的优化策略

现代构建工具会进行"tree-shaking"（摇树优化），移除未被使用的代码。对于被标记为无副作用的函数，构建工具会更加激进地移除那些看似无用的调用。

解决方案

Valibot 的维护者迅速响应并修复了这个问题，移除了 parse 函数上的 @__NO_SIDE_EFFECTS__ 注解。这样构建工具就不会错误地移除那些可能抛出异常的函数调用了。

经验教训

1. 谨慎使用优化注解：像 @__NO_SIDE_EFFECTS__ 这样的注解虽然能提高构建效率，但必须确保函数确实没有副作用才能使用。

2. 异常处理是副作用：任何可能抛出异常的函数都不应该被标记为无副作用。

3. 测试生产构建：开发环境和生产构建的行为可能不同，特别是在使用了高级优化的情况下，应该充分测试生产构建。

4. 库设计考虑：作为库开发者，需要仔细考虑每个API的行为特性，避免给使用者带来意外的行为。

总结

这个案例展示了JavaScript生态中构建优化与函数行为声明之间的微妙关系。Valibot团队的快速响应展示了良好的开源维护实践。对于开发者而言，理解构建工具的工作原理和函数副作用的概念，能够帮助我们更好地诊断和解决类似的问题。