Fastify框架入门：如何编写你的第一个ESM插件

在Node.js生态中，Fastify作为一款高性能的Web框架，其插件系统是扩展功能的核心机制。随着ECMAScript Modules（ESM）逐渐成为JavaScript模块化的标准，开发者需要了解如何在Fastify中编写符合ESM规范的插件。

传统CommonJS与ESM的差异

传统Fastify插件通常采用CommonJS规范，通过module.exports导出插件函数。但在ESM规范下，需要使用export default语法。这种差异会导致直接转换时代码无法正常运行，特别是当插件需要被Fastify正确加载时。

ESM插件的正确写法

一个标准的Fastify ESM插件应该这样定义：

// plugin.mjs
import fastifyPlugin from 'fastify-plugin';

async function myPlugin(fastify, options) {
  fastify.decorate('utility', () => {
    // 插件功能实现
  });
}

export default fastifyPlugin(myPlugin);

关键点在于：

1. 使用.mjs扩展名明确表示这是ESM模块
2. 通过fastify-plugin包装器确保插件上下文正确
3. 使用export default而非module.exports

项目配置注意事项

要使ESM插件正常工作，还需确保：

1. 在package.json中添加"type": "module"字段
2. 或者使用.mjs文件扩展名
3. 确保Node.js版本支持ESM（建议14.x以上）

插件开发最佳实践

无论采用哪种模块系统，良好的Fastify插件应该：

1. 明确声明依赖：通过fastify-plugin的dependencies选项
2. 提供类型定义：对TypeScript用户友好
3. 包含清晰的文档：说明插件功能和选项
4. 进行适当的错误处理

总结

随着JavaScript生态向ESM迁移，Fastify插件开发也需要与时俱进。理解ESM规范下的插件编写方式，不仅能让代码更符合现代标准，还能避免常见的模块加载错误。对于新项目，建议直接从ESM规范开始，以获得更好的长期维护性和兼容性。