当前位置：首页 > news >正文

Scully插件开发完全指南：从零编写自定义插件

news 2026/6/7 9:07:02

Scully插件开发完全指南：从零编写自定义插件

【免费下载链接】scullyThe Static Site Generator for Angular apps项目地址: https://gitcode.com/gh_mirrors/sc/scully

Scully是Angular应用的静态网站生成器，通过插件系统可以轻松扩展其功能。本文将带你从零开始创建一个Scully插件，无需深厚的Angular知识，只需基础的JavaScript/TypeScript技能即可上手。

为什么选择Scully插件开发？

Scully作为Angular生态中领先的静态站点生成工具，其插件系统提供了无限可能。无论是内容转换、路由处理还是性能优化，插件都能帮助你定制专属的静态站点生成流程。

Scully的核心优势在于将Angular应用预渲染为静态HTML，插件系统让这一过程更加灵活可控

插件开发准备工作

环境搭建

首先确保你的开发环境中已安装Node.js和npm，然后通过以下命令克隆Scully项目：

git clone https://gitcode.com/gh_mirrors/sc/scully cd scully npm install

了解插件类型

Scully提供多种插件类型，适用于不同场景：

路由插件(router)：处理路由发现和生成，如libs/plugins/from-data/src/lib/plugins-from-data.ts
内容处理插件(fileHandler)：处理不同格式的内容文件，如Markdown、AsciiDoc
DOM处理插件(postProcessByDom)：修改生成的HTML内容，如libs/plugins/scully-plugin-copy-to-clipboard/src/lib/plugins-scully-plugin-copy-to-clipboard.ts
系统插件(scullySystem)：参与Scully的核心流程，如渲染、文件写入等

从零创建你的第一个插件

步骤1：创建插件文件

在libs/plugins目录下创建新的插件文件夹和文件：

mkdir -p libs/plugins/hello-world/src/lib touch libs/plugins/hello-world/src/lib/hello-world.plugin.ts

步骤2：编写插件函数

一个基本的Scully插件是一个返回特定接口的函数。以下是一个简单的"Hello World"插件示例：

// hello-world.plugin.ts import { registerPlugin } from '@scullyio/scully'; export function helloWorldPlugin() { return async (html: string) => { // 在HTML头部添加问候语注释 return `<!-- Hello from Scully Plugin! -->\n${html}`; }; } // 注册插件 registerPlugin('postProcessByHtml', 'helloWorld', helloWorldPlugin);

步骤3：注册插件

使用registerPlugin函数将你的插件注册到Scully系统。注册时需要指定：

插件类型（如'postProcessByHtml'）
插件名称（如'helloWorld'）
插件函数
可选的验证器

示例注册代码：

// 注册DOM处理插件 registerPlugin('postProcessByDom', 'helloWorld', helloWorldPlugin); // 注册路由插件 registerPlugin('router', 'helloWorldRoutes', helloWorldRoutePlugin, validator);

插件开发进阶技巧

添加配置验证

为插件添加配置验证确保用户提供正确的参数：

import { Joi } from '@scullyio/scully'; const validator = Joi.object({ message: Joi.string().required().description('问候消息内容') }); registerPlugin('postProcessByHtml', 'helloWorld', helloWorldPlugin, validator);

处理异步操作

许多插件需要执行异步操作，如API调用或文件读写：

export async function fetchDataPlugin() { return async (html: string) => { const data = await fetch('https://api.example.com/data'); const content = await data.text(); return html.replace('{{externalData}}', content); }; }

使用Scully工具函数

Scully提供了丰富的工具函数库，可在libs/scully/src/lib/utils中找到，帮助你处理文件、路径和DOM操作。

测试你的插件

本地测试

在Scully配置文件中添加你的插件：

// scully.config.ts export const config: ScullyConfig = { projectRoot: './src', plugins: { helloWorld: { message: 'Hello from config!' } }, routes: { '/blog/:slug': { type: 'contentFolder', slug: { folder: './blog' } } } };

运行Scully生成命令测试插件效果：

npx scully

调试技巧

使用console.log输出调试信息
利用VS Code的断点调试功能
查看Scully生成的日志文件

发布和分享你的插件

打包插件

创建package.json文件，指定插件的入口点：

{ "name": "@scullyio/hello-world", "main": "src/lib/hello-world.plugin.ts", "peerDependencies": { "@scullyio/scully": "latest" } }

文档和示例

为你的插件创建详细文档，包括：

安装说明
配置选项
使用示例
已知限制

可以参考官方插件文档结构：docs/Reference/plugins/community-plugins

常见插件示例

内容转换插件

类似于libs/plugins/scully-plugin-critical-css/src/lib/plugins-scully-plugin-critical-css.ts，处理HTML并注入关键CSS：

export function criticalCssPlugin() { return async (html: string) => { // 处理HTML，提取并注入关键CSS return processedHtml; }; } registerPlugin('postProcessByHtml', 'criticalCSS', criticalCssPlugin);

路由生成插件

类似于libs/plugins/extra/src/lib/plugins-extra.ts，生成额外的路由：

export async function extraRoutesPlugin(route: string, config) { const extraRoutes = await fetchExtraRoutes(config.apiUrl); return extraRoutes.map(route => ({ route: `/extra/${route.id}`, title: route.title })); } registerPlugin('router', 'extra', extraRoutesPlugin, validator);