Modern.js 框架插件开发指南：核心 API 详解

前言

Modern.js 作为一款现代化的前端开发框架，其插件系统是框架扩展能力的核心。本文将深入解析 Modern.js 插件开发中的关键 API，帮助开发者更好地理解和利用框架的扩展能力。

插件基础结构

在 Modern.js 中，插件的基本结构如下：

import type { CliPlugin } from '@modern-js/core';

export const myPlugin = (): CliPlugin => ({
  name: 'my-plugin',  // 插件名称
  setup(api) {        // 插件安装函数
    // 在这里使用各种 API
  },
});

核心 API 解析

1. 配置获取 API

useConfigContext

作用：获取用户原始配置

const config = api.useConfigContext();

• 返回的是用户在配置文件中编写的原始配置
• 配置对象是只读的，不能直接修改
• 包含 source、output、server 等配置项

典型使用场景：

• 需要读取用户配置进行逻辑判断
• 根据用户配置决定插件行为

useResolvedConfigContext

作用：获取解析后的最终配置

const resolvedConfig = api.useResolvedConfigContext();

• 返回的是经过框架处理后的标准化配置
• 包含 _raw 字段保存原始配置
• 所有配置项都已标准化，带有默认值

与 useConfigContext 的区别：

• 原始配置可能缺少某些字段
• 解析后的配置所有字段都有值
• 解析后的配置更适合插件内部使用

2. 应用上下文 API

useAppContext

作用：获取应用运行时上下文

const appContext = api.useAppContext();

重要字段说明：

字段	类型	说明
appDirectory	string	项目根目录
srcDirectory	string	源代码目录
distDirectory	string	构建输出目录
packageName	string	package.json 中的名称
entrypoints	Entrypoint[]	入口点信息
serverRoutes	ServerRoute[]	服务端路由信息
bundlerType	string	使用的打包工具类型

注意事项：

• 上下文信息是动态变化的
• 不同阶段获取的值可能不同
• 目录相关字段都是绝对路径

3. Hook 执行器 API

useHookRunners

作用：获取 Hook 执行器，触发特定 Hook

const hookRunners = api.useHookRunners();
await hookRunners.afterBuild();

使用建议：

• 谨慎调用内置 Hook
• 主要用于触发自定义 Hook
• 异步 Hook 需要使用 await

最佳实践

1. 配置读取：

   • 优先使用解析后的配置
   • 需要修改配置时使用 config Hook

2. 上下文使用：

   • 避免缓存上下文对象
   • 需要时实时获取最新值
   • 注意路径字段在不同环境下的差异

3. Hook 调用：

   • 不要随意调用框架内置 Hook
   • 异步 Hook 要正确处理 Promise
   • 考虑 Hook 的执行顺序

常见问题

Q: 如何修改用户配置？ A: 需要通过 config Hook 进行修改，直接修改配置对象无效。

Q: 为什么我的插件获取的目录路径不对？ A: 确保在正确的阶段获取上下文，某些目录可能在后期才会创建。

Q: 可以自定义 Hook 吗？ A: 可以，通过定义和触发自定义 Hook 实现插件间通信。

总结

Modern.js 的插件 API 设计简洁而强大，通过配置获取、上下文访问和 Hook 机制三个维度提供了完整的扩展能力。理解这些 API 的特性和使用场景，能够帮助开发者编写出更加健壮、灵活的插件。

在实际开发中，建议结合具体需求选择合适的 API，并遵循框架的最佳实践，确保插件的稳定性和兼容性。