Hexo 主题开发系列教程（五）：插件系统与生态

/**
 * Hexo 启动时的插件加载过程
 */

// 1. 初始化 Hexo 实例
const Hexo = require('hexo');
const hexo = new Hexo(process.cwd());

// 2. 加载配置
hexo.init()
  // 3. 扫描并加载插件
  .then(() => loadPlugins(hexo))
  // 4. 加载主题
  .then(() => hexo.loadTheme())
  // 5. 执行命令
  .then(() => hexo.call(command, args));

// 模式 1：函数式（最常用）
module.exports = function(hexo) {
  const config = Object.assign({
    enable: true
  }, hexo.config.plugin_example);
  
  if (!config.enable) return;
  
  // 注册扩展
  require('./lib/filter')(hexo);
  require('./lib/generator')(hexo);
};

// 模式 2：对象式
module.exports = {
  init: function(hexo) {
    // 初始化逻辑
  },
  metadata: {
    name: 'hexo-plugin-example',
    version: '1.0.0'
  }
};

// 模式 3：类式（复杂插件）
class Plugin {
  constructor(hexo) {
    this.hexo = hexo;
    this.config = this.loadConfig();
  }
  
  init() {
    this.registerFilters();
  }
}

module.exports = function(hexo) {
  const plugin = new Plugin(hexo);
  plugin.init();
};

'use strict';

module.exports = function(hexo) {
  const config = Object.assign({
    enable: true,
    jpg: { quality: 80 },
    png: { quality: [0.6, 0.8] },
    webp: { enable: false }
  }, hexo.config.image_optimizer);
  
  if (!config.enable) return;
  
  // 生成后优化图片
  hexo.extend.filter.register('after_generate', async function() {
    const images = getAllImages(hexo.public_dir);
    
    for (const img of images) {
      await optimizeImage(img, config);
    }
    
    hexo.log.info(`[image-optimizer] Optimized ${images.length} images`);
  });
  
  // Helper：响应式图片
  hexo.extend.helper.register('responsive_image', function(src, alt) {
    return `
      <picture>
        <source srcset="${src}.webp" type="image/webp">
        <img src="${src}" alt="${alt}" loading="lazy">
      </picture>
    `;
  });
};

module.exports = function(hexo) {
  const storage = require('./lib/storage')(hexo);
  
  // Helper：显示阅读量
  hexo.extend.helper.register('reading_count', function(path) {
    return storage.getCount(path);
  });
  
  // 注入客户端脚本
  hexo.extend.filter.register('after_render:html', function(str) {
    const script = '<script src="/reading-stats.js"></script>';
    return str.replace('</body>', script + '</body>');
  });
  
  // API 路由
  hexo.extend.generator.register('reading-api', function() {
    return {
      path: 'api/reading-stats.json',
      data: storage.getAll()
    };
  });
};

// public/reading-stats.js
(function() {
  const path = window.location.pathname;
  
  // 记录阅读（防重复）
  if (!localStorage.getItem(`read_${path}`)) {
    setTimeout(() => {
      localStorage.setItem(`read_${path}`, Date.now());
      updateCount(path);
    }, 5000); // 停留5秒后记录
  }
  
  // 更新显示
  async function updateCount(path) {
    const response = await fetch('/api/reading-stats.json');
    const data = await response.json();
    document.querySelector('.reading-count').textContent = data[path] || 0;
  }
})();

'use strict';

module.exports = function(hexo) {
  // 在代码块后添加复制按钮
  hexo.extend.filter.register('after_post_render', function(data) {
    const $ = require('cheerio').load(data.content);
    
    $('pre code').each(function() {
      const $code = $(this);
      const $pre = $code.parent();
      
      // 添加复制按钮
      $pre.prepend(`
        <button class="copy-btn" data-clipboard-text="${$code.text()}">
          复制代码
        </button>
      `);
    });
    
    data.content = $.html();
    return data;
  });
  
  // 注入 Clipboard.js
  hexo.extend.injector.register('head_end', `
    <link rel="stylesheet" href="/css/code-copy.css">
  `);
  
  hexo.extend.injector.register('body_end', `
    <script src="https://cdn.jsdelivr.net/npm/clipboard@2/dist/clipboard.min.js"></script>
    <script>
      new ClipboardJS('.copy-btn').on('success', function(e) {
        e.trigger.textContent = '已复制!';
        setTimeout(() => e.trigger.textContent = '复制代码', 2000);
      });
    </script>
  `);
};

/**
 * hexo-generator-index 核心逻辑
 */

hexo.extend.generator.register('index', function(locals) {
  const config = this.config;
  const posts = locals.posts.sort(config.index_generator.order_by || '-date');
  const perPage = config.index_generator.per_page || 10;
  const paginationDir = config.pagination_dir || 'page';
  
  return pagination('', posts, {
    perPage: perPage,
    layout: ['index', 'archive'],
    format: paginationDir + '/%d/',
    data: {
      __index: true
    }
  });
});

/**
 * hexo-generator-archive 核心逻辑
 */

hexo.extend.generator.register('archive', function(locals) {
  const config = this.config;
  const archiveConfig = config.archive_generator;
  const posts = locals.posts.sort('-date');
  const perPage = archiveConfig.per_page || 10;
  
  const routes = [];
  
  // 1. 生成总归档页
  routes.push({
    path: archiveConfig.path || 'archives/',
    data: posts,
    layout: ['archive', 'index']
  });
  
  // 2. 按年归档
  if (archiveConfig.yearly) {
    const yearPosts = {};
    
    posts.forEach(post => {
      const year = post.date.year();
      if (!yearPosts[year]) yearPosts[year] = [];
      yearPosts[year].push(post);
    });
    
    Object.keys(yearPosts).forEach(year => {
      routes.push({
        path: `archives/${year}/`,
        data: yearPosts[year],
        layout: ['archive', 'index'],
        year: year
      });
    });
  }
  
  // 3. 按月归档
  if (archiveConfig.monthly) {
    const monthPosts = {};
    
    posts.forEach(post => {
      const year = post.date.year();
      const month = post.date.format('MM');
      const key = `${year}/${month}`;
      
      if (!monthPosts[key]) monthPosts[key] = [];
      monthPosts[key].push(post);
    });
    
    Object.keys(monthPosts).forEach(key => {
      const [year, month] = key.split('/');
      routes.push({
        path: `archives/${key}/`,
        data: monthPosts[key],
        layout: ['archive', 'index'],
        year: year,
        month: month
      });
    });
  }
  
  return routes;
});

/**
 * hexo-generator-category 核心逻辑
 */

hexo.extend.generator.register('category', function(locals) {
  const config = this.config;
  const categoryConfig = config.category_generator;
  const categories = locals.categories;
  
  return categories.reduce((result, category) => {
    if (!category.length) return result;
    
    const posts = category.posts.sort('-date');
    const path = category.path;
    
    // 生成分类页面
    result.push({
      path: path,
      data: category,
      layout: ['category', 'archive', 'index']
    });
    
    // 如果开启分页
    if (categoryConfig.per_page > 0) {
      const pages = Math.ceil(posts.length / categoryConfig.per_page);
      
      for (let i = 2; i <= pages; i++) {
        result.push({
          path: `${path}page/${i}/`,
          data: category,
          layout: ['category', 'archive', 'index'],
          current: i
        });
      }
    }
    
    return result;
  }, []);
});

/**
 * hexo-generator-tag 核心逻辑
 */

hexo.extend.generator.register('tag', function(locals) {
  const config = this.config;
  const tagConfig = config.tag_generator;
  const tags = locals.tags;
  
  return tags.reduce((result, tag) => {
    if (!tag.length) return result;
    
    const posts = tag.posts.sort('-date');
    const path = tag.path;
    
    // 生成标签页面
    result.push({
      path: path,
      data: tag,
      layout: ['tag', 'archive', 'index']
    });
    
    // 分页
    if (tagConfig.per_page > 0) {
      const pages = Math.ceil(posts.length / tagConfig.per_page);
      
      for (let i = 2; i <= pages; i++) {
        result.push({
          path: `${path}page/${i}/`,
          data: tag,
          layout: ['tag', 'archive', 'index'],
          current: i
        });
      }
    }
    
    return result;
  }, []);
});

/**
 * hexo-renderer-ejs 核心逻辑
 */

const ejs = require('ejs');

hexo.extend.renderer.register('ejs', 'html', function(data, options) {
  // 编译 EJS 模板
  return ejs.render(data.text, {
    ...options,
    filename: data.path
  });
}, true);

/**
 * hexo-renderer-marked 核心逻辑
 */

const { marked } = require('marked');
const stripIndent = require('strip-indent');

hexo.extend.renderer.register('md', 'html', function(data, options) {
  const config = this.config.marked || {};
  
  // 配置 marked
  marked.setOptions({
    gfm: config.gfm !== false,
    breaks: config.breaks !== false,
    pedantic: config.pedantic || false,
    sanitize: config.sanitize || false,
    smartLists: config.smartLists !== false,
    smartypants: config.smartypants !== false,
    highlight: function(code, lang) {
      // 代码高亮
      return highlightCode(code, lang);
    }
  });
  
  // 渲染 Markdown
  return marked(stripIndent(data.text));
}, true);

/**
 * hexo-renderer-stylus 核心逻辑
 */

const stylus = require('stylus');
const nib = require('nib');

hexo.extend.renderer.register('styl', 'css', function(data, options) {
  const config = this.config.stylus || {};
  
  return new Promise((resolve, reject) => {
    stylus(data.text)
      .set('filename', data.path)
      .set('compress', config.compress || false)
      .set('include css', true)
      .use(nib())
      .render((err, css) => {
        if (err) reject(err);
        else resolve(css);
      });
  });
}, true);

/**
 * Hexo 生成流程中的插件协作
 */

// 1. 用户执行 hexo generate
hexo.call('generate')

// 2. hexo-renderer-marked 渲染 Markdown
//    source/_posts/hello.md → 渲染为 HTML

// 3. Generator 插件开始工作
//    hexo-generator-index → 生成首页
//    hexo-generator-archive → 生成归档页
//    hexo-generator-category → 生成分类页
//    hexo-generator-tag → 生成标签页

// 4. hexo-renderer-ejs 渲染模板
//    layout/index.ejs → 应用数据 → 生成 HTML

// 5. hexo-renderer-stylus 渲染样式
//    source/css/style.styl → 生成 CSS

// 6. 输出到 public 目录
public/
├── index.html
├── archives/
├── categories/
├── tags/
├── css/
└── ...

// scripts/extend-generators.js

/**
 * 扩展 index generator，添加 RSS 链接
 */
hexo.extend.filter.register('before_generate', function() {
  const original = hexo.extend.generator.get('index');
  
  hexo.extend.generator.register('index', function(locals) {
    const result = original.call(this, locals);
    
    // 添加 RSS feed 到首页数据
    if (result && result[0]) {
      result[0].data.feed_url = '/atom.xml';
    }
    
    return result;
  });
});

// scripts/optimize-generators.js

/**
 * 缓存 Generator 结果
 */
const cache = new Map();

hexo.extend.filter.register('before_generate', function() {
  cache.clear();
});

function cachedGenerator(name, fn) {
  return function(locals) {
    const key = JSON.stringify(locals);
    
    if (cache.has(key)) {
      hexo.log.debug(`[Cache] Hit: ${name}`);
      return cache.get(key);
    }
    
    const result = fn.call(this, locals);
    cache.set(key, result);
    return result;
  };
}

// 应用缓存
hexo.extend.generator.register('index', 
  cachedGenerator('index', originalIndexGenerator)
);

// scripts/generator-timeline.js

/**
 * 时间线生成器
 * 按时间轴展示所有文章
 */

hexo.extend.generator.register('timeline', function(locals) {
  const posts = locals.posts.sort('-date');
  const timeline = {};
  
  // 按年月分组
  posts.forEach(post => {
    const year = post.date.year();
    const month = post.date.format('MM');
    
    if (!timeline[year]) {
      timeline[year] = {};
    }
    
    if (!timeline[year][month]) {
      timeline[year][month] = [];
    }
    
    timeline[year][month].push({
      title: post.title,
      path: post.path,
      date: post.date.format('YYYY-MM-DD'),
      excerpt: post.excerpt
    });
  });
  
  // 生成页面
  return {
    path: 'timeline/index.html',
    layout: ['timeline', 'page'],
    data: {
      timeline: timeline,
      total: posts.length
    }
  };
});

// themes/aurora/scripts/plugin-detect.js

hexo.extend.filter.register('before_generate', function() {
  const plugins = {
    feed: 'hexo-generator-feed',
    sitemap: 'hexo-generator-sitemap',
    wordcount: 'hexo-wordcount'
  };
  
  Object.keys(plugins).forEach(key => {
    const pluginName = plugins[key];
    const hasPlugin = hexo.extend.helper.list()[key] !== undefined ||
                     hexo.extend.generator.list()[key] !== undefined;
    
    hexo.theme.config[`has_${key}`] = hasPlugin;
    
    if (!hasPlugin) {
      hexo.log.warn(`[Aurora] Plugin ${pluginName} not found`);
    }
  });
});

// 主题定义钩子
hexo.extend.filter.register('theme_custom_render', function(data) {
  // 插件可以在这里添加自定义处理
  return data;
});

// 插件使用钩子
hexo.extend.filter.register('theme_custom_render', function(data) {
  // 添加自定义功能
  data.custom = 'value';
  return data;
});

const Hexo = require('hexo');
const { expect } = require('chai');

describe('Filter Tests', () => {
  let hexo;
  
  beforeEach(() => {
    hexo = new Hexo(__dirname);
    require('../index')(hexo);
  });
  
  it('should register filter', () => {
    const filters = hexo.extend.filter.list();
    expect(filters).to.have.property('after_post_render');
  });
  
  it('should process content', async () => {
    const data = {
      content: '<img src="test.jpg">'
    };
    
    const filter = hexo.extend.filter.get('after_post_render')[0];
    const result = await filter(data);
    
    expect(result.content).to.include('loading="lazy"');
  });
});

// ✅ 使用缓存
const cache = new Map();

hexo.extend.helper.register('expensive_operation', function(data) {
  const key = JSON.stringify(data);
  
  if (!cache.has(key)) {
    cache.set(key, processData(data));
  }
  
  return cache.get(key);
});

// ✅ 异步处理
hexo.extend.filter.register('after_generate', async function() {
  await Promise.all(
    images.map(img => optimizeImage(img))
  );
});

// ❌ 避免同步阻塞
hexo.extend.filter.register('after_generate', function() {
  images.forEach(img => {
    fs.writeFileSync(img, data); // 阻塞
  });
});

hexo.extend.filter.register('after_post_render', function(data) {
  try {
    return processData(data);
  } catch (err) {
    hexo.log.error('Processing failed:', err);
    return data; // 返回原数据，不中断流程
  }
});

function validateConfig(config) {
  const required = ['apiKey', 'apiSecret'];
  
  for (const key of required) {
    if (!config[key]) {
      throw new Error(`Missing required config: ${key}`);
    }
  }
  
  return true;
}

// 使用统一前缀
hexo.log.info('[plugin-name] Started');
hexo.log.warn('[plugin-name] Warning message');
hexo.log.error('[plugin-name] Error message');
hexo.log.debug('[plugin-name] Debug info');

// 检查 Hexo 版本
const hexoVersion = require('hexo/package.json').version;
const semver = require('semver');

if (!semver.satisfies(hexoVersion, '>=5.0.0')) {
  hexo.log.error('This plugin requires Hexo >= 5.0.0');
  return;
}

// 检查依赖插件
if (!hexo.extend.helper.get('markdown')) {
  hexo.log.warn('hexo-renderer-marked is required');
}

// Plugin A: 发布事件
hexo.extend.filter.register('after_generate', function() {
  hexo.emit('custom:event', { data: 'value' });
});

// Plugin B: 监听事件
hexo.on('custom:event', function(data) {
  console.log('Received:', data);
});

module.exports = function(hexo) {
  // 只在生产环境加载
  if (process.env.NODE_ENV === 'production') {
    require('./lib/production')(hexo);
  }
  
  // 只在开发环境加载
  if (hexo.env.cmd === 'server') {
    require('./lib/development')(hexo);
  }
};

// hexo-plugin-manager
class PluginManager {
  constructor(hexo) {
    this.hexo = hexo;
    this.plugins = new Map();
  }
  
  register(name, plugin) {
    this.plugins.set(name, plugin);
  }
  
  get(name) {
    return this.plugins.get(name);
  }
  
  enable(name) {
    const plugin = this.get(name);
    if (plugin) plugin.enable();
  }
  
  disable(name) {
    const plugin = this.get(name);
    if (plugin) plugin.disable();
  }
}