Cordis 入门 01：从零跑起第一个插件

学 Cordis 最容易卡住的地方，不是 API 多，而是它的入口不像常见 Web 框架。你不会一上来写 Controller、Route 或 Component，而是先创建一个 Context，再把一个函数安装成插件。

这篇先不讲论文里的"时空可组合性"，也不读源码。目标只有一个：把第一个 Cordis 插件跑起来，并理解 Context、Plugin、Fiber 这三个词。

这篇要练什么

练完本文，你会得到一个最小 cordis-demo 项目：

text 复制代码

cordis-demo
├─ package.json
└─ index.mjs

你会掌握三件事：

用 new Context() 创建 Cordis 运行时。
用 ctx.plugin() 安装一个插件。
用 Fiber 理解插件安装后的运行实例。

准备项目

创建项目目录并安装 Cordis。

bash 复制代码

mkdir cordis-demo
cd cordis-demo
npm init -y
npm install cordis@4.0.0-rc.8

本文示例基于 cordis@4.0.0-rc.8 验证。Cordis 当前仍是 rc 版本，跟练时建议先锁定版本，避免未来 API 调整影响学习过程。

当前 npm 上的 cordis 是 ESM 包。为了降低入门成本，本文示例统一使用 .mjs 文件。

创建 index.mjs：

js 复制代码

import { Context } from 'cordis'

const ctx = new Context()

function helloPlugin(ctx) {
  console.log('hello cordis')
}

await ctx.plugin(helloPlugin)

运行：

bash 复制代码

node index.mjs

如果输出下面这行，说明第一个插件已经跑起来了。

text 复制代码

hello cordis

这段代码到底发生了什么

先把代码拆成三层。
#mermaid-svg-RJxyZgvlwBbltZUK{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-RJxyZgvlwBbltZUK .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-RJxyZgvlwBbltZUK .error-icon{fill:#552222;}#mermaid-svg-RJxyZgvlwBbltZUK .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-RJxyZgvlwBbltZUK .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-RJxyZgvlwBbltZUK .marker{fill:#333333;stroke:#333333;}#mermaid-svg-RJxyZgvlwBbltZUK .marker.cross{stroke:#333333;}#mermaid-svg-RJxyZgvlwBbltZUK svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-RJxyZgvlwBbltZUK p{margin:0;}#mermaid-svg-RJxyZgvlwBbltZUK .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-RJxyZgvlwBbltZUK .cluster-label text{fill:#333;}#mermaid-svg-RJxyZgvlwBbltZUK .cluster-label span{color:#333;}#mermaid-svg-RJxyZgvlwBbltZUK .cluster-label span p{background-color:transparent;}#mermaid-svg-RJxyZgvlwBbltZUK .label text,#mermaid-svg-RJxyZgvlwBbltZUK span{fill:#333;color:#333;}#mermaid-svg-RJxyZgvlwBbltZUK .node rect,#mermaid-svg-RJxyZgvlwBbltZUK .node circle,#mermaid-svg-RJxyZgvlwBbltZUK .node ellipse,#mermaid-svg-RJxyZgvlwBbltZUK .node polygon,#mermaid-svg-RJxyZgvlwBbltZUK .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-RJxyZgvlwBbltZUK .rough-node .label text,#mermaid-svg-RJxyZgvlwBbltZUK .node .label text,#mermaid-svg-RJxyZgvlwBbltZUK .image-shape .label,#mermaid-svg-RJxyZgvlwBbltZUK .icon-shape .label{text-anchor:middle;}#mermaid-svg-RJxyZgvlwBbltZUK .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-RJxyZgvlwBbltZUK .rough-node .label,#mermaid-svg-RJxyZgvlwBbltZUK .node .label,#mermaid-svg-RJxyZgvlwBbltZUK .image-shape .label,#mermaid-svg-RJxyZgvlwBbltZUK .icon-shape .label{text-align:center;}#mermaid-svg-RJxyZgvlwBbltZUK .node.clickable{cursor:pointer;}#mermaid-svg-RJxyZgvlwBbltZUK .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-RJxyZgvlwBbltZUK .arrowheadPath{fill:#333333;}#mermaid-svg-RJxyZgvlwBbltZUK .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-RJxyZgvlwBbltZUK .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-RJxyZgvlwBbltZUK .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RJxyZgvlwBbltZUK .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-RJxyZgvlwBbltZUK .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RJxyZgvlwBbltZUK .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-RJxyZgvlwBbltZUK .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-RJxyZgvlwBbltZUK .cluster text{fill:#333;}#mermaid-svg-RJxyZgvlwBbltZUK .cluster span{color:#333;}#mermaid-svg-RJxyZgvlwBbltZUK div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-RJxyZgvlwBbltZUK .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-RJxyZgvlwBbltZUK rect.text{fill:none;stroke-width:0;}#mermaid-svg-RJxyZgvlwBbltZUK .icon-shape,#mermaid-svg-RJxyZgvlwBbltZUK .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RJxyZgvlwBbltZUK .icon-shape p,#mermaid-svg-RJxyZgvlwBbltZUK .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-RJxyZgvlwBbltZUK .icon-shape .label rect,#mermaid-svg-RJxyZgvlwBbltZUK .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RJxyZgvlwBbltZUK .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-RJxyZgvlwBbltZUK .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-RJxyZgvlwBbltZUK :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} new Context()
创建 Cordis 运行时上下文
ctx.plugin(helloPlugin)
Cordis 执行插件函数
插件进入自己的 Fiber 生命周期

Context 是 Cordis 的运行时上下文。插件需要事件、服务、子插件、生命周期能力时，都会从 ctx 进去。

Plugin 在这个例子里就是 helloPlugin 函数。Cordis 支持函数、类和带 apply 方法的对象作为插件。入门阶段先用函数插件最清楚。

Fiber 是插件被安装后的生命周期实例。你可以先把它理解成"这个插件这一次运行的身份"。后面插件卸载、副作用清理、依赖等待，都会围绕 Fiber 展开。

拿到 Fiber

ctx.plugin() 会返回一个 Fiber。这个 Fiber 也可以被 await。

把 index.mjs 改成下面这样：

js 复制代码

import { Context } from 'cordis'

const ctx = new Context()

function helloPlugin(ctx) {
  console.log('hello cordis')
}

const fiber = ctx.plugin(helloPlugin)
await fiber

console.log('plugin is ready')

运行：

bash 复制代码

node index.mjs

输出：

text 复制代码

hello cordis
plugin is ready

这个例子里插件很简单，所以 await fiber 几乎立刻结束。后面当插件依赖某个服务时，await fiber 就会变得重要：它表示等待插件真正进入可用状态。

插件可以接收配置

大多数插件都需要配置。Cordis 会把第二个参数传给插件函数。

js 复制代码

import { Context } from 'cordis'

const ctx = new Context()

function greetPlugin(ctx, config) {
  console.log(`hello ${config.name}`)
}

await ctx.plugin(greetPlugin, {
  name: 'cordis',
})

运行后输出：

text 复制代码

hello cordis

配置对象现在只是普通对象。更严格的配置校验可以以后再学。入门阶段先把插件函数的两个参数记住：

text 复制代码

plugin(ctx, config)

一个小练习

把 greetPlugin 改成下面的需求：

配置里传入 name。
配置里传入 times。
插件按次数打印问候语。

参考实现：

js 复制代码

import { Context } from 'cordis'

const ctx = new Context()

function greetPlugin(ctx, config) {
  for (let i = 0; i < config.times; i++) {
    console.log(`hello ${config.name} #${i + 1}`)
  }
}

await ctx.plugin(greetPlugin, {
  name: 'cordis',
  times: 3,
})

输出：

text 复制代码

hello cordis #1
hello cordis #2
hello cordis #3

入门检查点

现在你可以把 Cordis 先理解成下面这句话：

text 复制代码

Cordis = Context + Plugin + Fiber

Context 是运行环境，Plugin 是功能单元，Fiber 是插件运行后的生命周期实例。

这一篇还没有体现 Cordis 最强的地方。真正的插件不只打印日志，它会注册事件、启动定时器、打开连接、提供服务。下一篇我们就处理第一个关键问题：插件产生副作用以后，卸载时怎么清理。

系列导航：

下一篇：Cordis 入门 02：用 effect 管好插件副作用
系列终篇：Cordis 入门 06：做一个迷你插件运行时