13.3 Plugin 加载机制

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

Plugin 的定义再精妙，如果无法被正确加载和初始化，也只是一纸空文。本节将解析 OpenCode 是如何发现、安装和加载 Plugin 的。

13.3.1 内置 Plugin

OpenCode 内置了三个认证 Plugin，它们通过直接 import 加载，不需要经过 npm 安装流程：

// plugin/index.ts
import { CodexAuthPlugin } from "./codex"
import { CopilotAuthPlugin } from "./copilot"
import { gitlabAuthPlugin as GitlabAuthPlugin } from "@gitlab/opencode-gitlab-auth"

const INTERNAL_PLUGINS: PluginInstance[] = [
  CodexAuthPlugin,
  CopilotAuthPlugin,
  GitlabAuthPlugin,
]

Plugin	功能
CodexAuthPlugin	为 OpenAI 的 Codex API 提供 OAuth 认证
CopilotAuthPlugin	为 GitHub Copilot 提供设备流 OAuth 认证
GitlabAuthPlugin	为 GitLab AI 提供 OAuth 认证

此外，还有一个内置的 npm Plugin（opencode-anthropic-auth），通过 npm 安装流程加载。

13.3.2 Plugin 加载流程

Plugin 的完整加载流程在 Instance.state() 的初始化函数中实现：

const state = Instance.state(async () => {
  const hooks: Hooks[] = []
  const input: PluginInput = { /* 构造上下文 */ }

  // 第一步：加载内部 Plugin
  for (const plugin of INTERNAL_PLUGINS) {
    const init = await plugin(input)
    hooks.push(init)
  }

  // 第二步：加载配置中声明的 Plugin
  let plugins = config.plugin ?? []
  if (plugins.length) await Config.waitForDependencies()
  if (!Flag.OPENCODE_DISABLE_DEFAULT_PLUGINS) {
    plugins = [...BUILTIN, ...plugins]
  }

  for (let plugin of plugins) {
    // 跳过已内置的旧版 Plugin
    if (plugin.includes("opencode-openai-codex-auth")) continue
    if (plugin.includes("opencode-copilot-auth")) continue

    if (!plugin.startsWith("file://")) {
      // npm 包 Plugin：动态安装
      const pkg = /* 解析包名 */
      const version = /* 解析版本号 */
      plugin = await BunProc.install(pkg, version)
    }

    // 动态导入 Plugin 模块
    const mod = await import(plugin)

    // 去重处理（防止同一函数同时作为 named export 和 default export）
    const seen = new Set<PluginInstance>()
    for (const [_name, fn] of Object.entries(mod)) {
      if (seen.has(fn)) continue
      seen.add(fn)
      const init = await fn(input)
      hooks.push(init)
    }
  }

  return { hooks, input }
})

npm 包 Plugin

当 Plugin 字符串不以 file:// 开头时，OpenCode 将其视为 npm 包，通过 BunProc.install() 动态安装：

// 解析 "[email protected]" → pkg="my-plugin", version="1.0.0"
const lastAtIndex = plugin.lastIndexOf("@")
const pkg = lastAtIndex > 0 ? plugin.substring(0, lastAtIndex) : plugin
const version = lastAtIndex > 0 ? plugin.substring(lastAtIndex + 1) : "latest"

// 使用 Bun 安装到全局缓存
plugin = await BunProc.install(pkg, version)

BunProc.install() 使用 bun install 将包安装到 OpenCode 的数据目录中，返回安装后的模块路径，然后通过 import() 动态加载。

本地文件 Plugin

以 file:// 开头的 Plugin 直接从本地文件系统加载：

{
  "plugin": [
    "file:///path/to/my-plugin.ts"
  ]
}

这种方式主要用于 Plugin 开发和调试——开发者不需要将 Plugin 发布到 npm 就可以测试。

去重处理

Plugin 模块可能同时导出命名导出和默认导出，指向同一个函数：

export const myPlugin: Plugin = async (ctx) => { /* ... */ }
export default myPlugin  // 与上面是同一个引用

如果不去重，Object.entries(mod) 会返回两个条目（myPlugin 和 default），导致 Plugin 被初始化两次。seen Set 通过引用比较（has(fn)）避免了这个问题。

13.3.3 容错处理

Plugin 加载过程中的错误被精心处理，确保单个 Plugin 的失败不会影响整个系统：

plugin = await BunProc.install(pkg, version).catch((err) => {
  if (!builtin) throw err  // 非内置 Plugin 的安装失败会终止

  // 内置 Plugin 安装失败只记录警告
  log.error("failed to install builtin plugin", { pkg, version, error: message })
  Bus.publish(Session.Event.Error, {
    error: new NamedError.Unknown({
      message: `Failed to install built-in plugin ${pkg}@${version}: ${message}`,
    }).toObject(),
  })
  return ""  // 返回空字符串，后续跳过
})
if (!plugin) continue  // 跳过安装失败的 Plugin

对于内置 Plugin，安装失败只会发出错误事件并继续加载其他 Plugin。对于用户配置的 Plugin，安装失败会抛出错误，因为用户显式声明了对该 Plugin 的依赖。

13.3.4 Plugin 初始化

加载完成后，Plugin.init() 执行两个初始化操作：

export async function init() {
  const hooks = await state().then((x) => x.hooks)
  const config = await Config.get()

  // 1. 调用每个 Plugin 的 config 钩子
  for (const hook of hooks) {
    await hook.config?.(config)
  }

  // 2. 将 Bus 事件转发给 Plugin 的 event 钩子
  Bus.subscribeAll(async (input) => {
    const hooks = await state().then((x) => x.hooks)
    for (const hook of hooks) {
      hook["event"]?.({ event: input })
    }
  })
}

13.3.5 小结

Plugin 加载机制支持三种来源，按加载顺序排列：

来源	加载方式	典型用途
内部 Plugin	直接 import	内置认证支持
npm 包 Plugin	BunProc.install() + 动态 import()	社区生态
本地文件 Plugin	直接 import("file://...")	开发调试

加载过程的可靠性由以下机制保证：

1. 容错降级：内置 Plugin 安装失败时继续运行。

2. 去重处理：防止同一 Plugin 被初始化两次。

3. 旧版跳过：已被内置替代的 Plugin 自动跳过。

4. 环境开关：OPENCODE_DISABLE_DEFAULT_PLUGINS 可禁用内置 Plugin。