脚手架与 CLI

要求 Node.js 22.12+。在工程中使用 npm scripts 或 npx ceru-plugin 调用本地 CLI，无需全局安装。各依赖的用途见开发环境与依赖。

创建与列出模板

npm create ceru-plugin@latest
npm create ceru-plugin@latest my-plugin -- --template vue --lang ts

第一种交互选择目录、模板和语言；第二种一次指定。已有本地 CLI 时也可以：

npx ceru-plugin list-templates
npx ceru-plugin init my-plugin --template source --lang js

模板来自 CLI 内置快照，创建时不会执行远端仓库脚本。九种模板的选择建议见模板页。

开发命令

命令	参数与默认值	用途
build	--project、--out	类型检查并构建单文件
dev	--port 4179、--debug-port 9223、--no-open	监听、构建并运行工作台
preview	plugin.js、端口参数	只运行指定成品
validate	plugin.js、可选可信公钥与 JSON 输出	检查结构、摘要和签名

npx ceru-plugin build --project . --out dist/plugin.js
npx ceru-plugin validate dist/plugin.js --json
npx ceru-plugin preview dist/plugin.js

失败命令会返回非零退出码，适合 CI。validate 不执行插件业务；签名有效也不表示代码安全。

端口与调试

npm run dev -- --port 4180 --debug-port 9224
npx ceru-plugin preview dist/plugin.js --port 4181 --debug-port 9225

--no-open 只启动本地服务，不自动打开工作台窗口。不要把开发工作台端口暴露到公网。

VS Code 调试：

1. 打开脚手架生成的 ceru-plugin.code-workspace。
2. 在“运行和调试”选择 “Launch Ceru plugin”，按 F5。
3. 已启动同一工程时选择 “Attach to Ceru plugin”。
4. 在 action 或 Provider 回调中打断点，再从工作台触发。
5. 激活代码已经执行时，点击工作台“重新运行”。

签名与发行命令

命令	结果
keygen --out .keys/publisher	生成发行公钥与私钥
sign plugin.js --key private.pem	生成签名插件
template plugin.js ...	创建可个性化发行模板
issue template.js ...	生成具体用户发行文件

完整顺序见签名与个性化发行。

检查本地工程依赖

npm ls @shiqianjiang/ceru-plugin-cli @shiqianjiang/ceru-plugin-sdk

npm ls 用来确认当前工程实际解析到的 CLI 和 SDK。构建时以锁文件和本地安装结果为准；不需要通过远程仓库查询“最新版本”来决定教程步骤。