Hexo 主题开发系列教程（一）：核心概念全解析

// 在初始化完成后触发
hexo.on('ready', function() {
  console.log('Hexo 已准备就绪');
});

// 在生成文件前触发
hexo.on('generateBefore', function() {
  console.log('开始生成静态文件');
});

// 在生成文件后触发
hexo.on('generateAfter', function() {
  console.log('静态文件生成完成');
});

// 在退出前触发
hexo.on('exit', function() {
  console.log('Hexo 正在退出');
});

// themes/your-theme/scripts/image-processor.js
hexo.on('generateBefore', function() {
  // 压缩图片、生成缩略图等操作
  const images = hexo.locals.get('images');
  images.forEach(img => {
    // 处理逻辑
  });
});

hexo.on('generateAfter', function() {
  // 生成搜索索引、站点地图等
  const posts = hexo.locals.get('posts');
  const searchData = posts.map(post => ({
    title: post.title,
    url: post.path,
    content: post.content
  }));
  // 保存数据
});

// 在模板中可直接访问的全局变量
site      // 网站信息
page      // 当前页面信息
config    // 网站配置
theme     // 主题配置
path      // 当前页面路径
url       // 当前页面完整URL
env       // 环境变量

// 作用域优先级（从高到低）
1. 页面级变量 (page)         // 当前页面特有的数据
2. 主题配置变量 (theme)      // 主题配置文件中的数据
3. 全局配置变量 (config)     // 站点配置文件中的数据
4. 站点变量 (site)           // 站点所有内容数据
5. Helper 函数              // 辅助函数返回的数据

// themes/your-theme/scripts/helpers.js

// 1. 简单数据返回
hexo.extend.helper.register('site_info', function() {
  return {
    author: this.config.author,
    posts_count: this.site.posts.length,
    pages_count: this.site.pages.length,
    tags_count: this.site.tags.length,
    categories_count: this.site.categories.length
  };
});

// 2. 带参数的 Helper
hexo.extend.helper.register('get_posts_by_year', function(year) {
  return this.site.posts.filter(post => {
    return post.date.year() === year;
  });
});

// 3. 复杂计算的 Helper
hexo.extend.helper.register('reading_stats', function() {
  const posts = this.site.posts;
  const totalWords = posts.reduce((sum, post) => {
    const words = post.content.replace(/<[^>]+>/g, '').split(/\s+/).length;
    return sum + words;
  }, 0);
  
  return {
    total_posts: posts.length,
    total_words: totalWords,
    avg_words: Math.round(totalWords / posts.length),
    total_reading_time: Math.ceil(totalWords / 200) // 假设每分钟200字
  };
});

// 4. 访问当前页面上下文的 Helper
hexo.extend.helper.register('is_current_path', function(path) {
  return this.path === path;
});

// 5. 组合多个数据源的 Helper
hexo.extend.helper.register('sidebar_data', function() {
  const recentPosts = this.site.posts.sort('date', -1).limit(5);
  const hotTags = this.site.tags.sort('length', -1).limit(10);
  
  return {
    recent_posts: recentPosts.toArray(),
    hot_tags: hotTags.toArray(),
    archive_count: this.site.posts.length,
    config: {
      show_categories: this.theme.sidebar.show_categories,
      show_tags: this.theme.sidebar.show_tags
    }
  };
});

// themes/your-theme/scripts/filters.js

// 1. 在模板渲染前注入变量
hexo.extend.filter.register('template_locals', function(locals) {
  // 添加自定义变量到所有模板
  locals.custom_menu = [
    { name: '首页', path: '/', icon: 'home' },
    { name: '归档', path: '/archives/', icon: 'archive' },
    { name: '关于', path: '/about/', icon: 'user' }
  ];
  
  // 添加当前年份
  locals.current_year = new Date().getFullYear();
  
  // 添加社交链接
  locals.social_links = this.theme.social || {};
  
  // 添加运行时间
  const startDate = new Date(this.config.site_start_date || '2020-01-01');
  const days = Math.floor((Date.now() - startDate) / (1000 * 60 * 60 * 24));
  locals.site_running_days = days;
  
  return locals;
});

// 2. 为特定页面类型添加变量
hexo.extend.filter.register('template_locals', function(locals) {
  // 只在文章页面添加相关文章
  if (locals.page.layout === 'post') {
    const currentPost = locals.page;
    const relatedPosts = locals.site.posts
      .filter(post => {
        // 排除当前文章
        if (post._id === currentPost._id) return false;
        
        // 查找有共同标签的文章
        if (currentPost.tags && post.tags) {
          const currentTags = currentPost.tags.map(t => t.name);
          const postTags = post.tags.map(t => t.name);
          const commonTags = currentTags.filter(t => postTags.includes(t));
          return commonTags.length > 0;
        }
        return false;
      })
      .sort('date', -1)
      .limit(5);
    
    locals.related_posts = relatedPosts.toArray();
  }
  
  // 为归档页面添加统计
  if (locals.page.layout === 'archive') {
    const posts = locals.site.posts;
    const yearStats = {};
    
    posts.forEach(post => {
      const year = post.date.year();
      yearStats[year] = (yearStats[year] || 0) + 1;
    });
    
    locals.archive_stats = yearStats;
  }
  
  return locals;
});

// 3. 修改文章数据
hexo.extend.filter.register('before_post_render', function(data) {
  // 为每篇文章添加估算阅读时间
  const words = data.content.replace(/<[^>]+>/g, '').split(/\s+/).length;
  data.reading_time = Math.ceil(words / 200);
  
  // 添加字数统计
  data.word_count = words;
  
  // 为文章添加更新状态
  if (data.updated) {
    const daysSinceUpdate = Math.floor(
      (Date.now() - data.updated.valueOf()) / (1000 * 60 * 60 * 24)
    );
    data.is_recent_update = daysSinceUpdate < 30;
    data.days_since_update = daysSinceUpdate;
  }
  
  // 自动生成摘要（如果没有手动指定）
  if (!data.excerpt && data.content) {
    const plainText = data.content.replace(/<[^>]+>/g, '');
    data.auto_excerpt = plainText.substring(0, 200) + '...';
  }
  
  return data;
});

// themes/your-theme/scripts/generator.js

// 生成标签云页面
hexo.extend.generator.register('tag-cloud', function(locals) {
  const tags = locals.tags.sort('length', -1);
  const maxCount = tags.first() ? tags.first().length : 1;
  const minCount = tags.last() ? tags.last().length : 1;
  
  // 计算每个标签的权重
  const tagCloud = tags.map(tag => {
    const weight = (tag.length - minCount) / (maxCount - minCount);
    const fontSize = 12 + Math.floor(weight * 20); // 12px - 32px
    
    return {
      name: tag.name,
      path: tag.path,
      count: tag.length,
      weight: weight,
      fontSize: fontSize
    };
  });
  
  return {
    path: 'tag-cloud/index.html',
    layout: 'tag-cloud',
    data: {
      title: '标签云',
      tags: tagCloud,
      total_tags: tags.length,
      total_posts: locals.posts.length
    }
  };
});

// 生成时间轴页面
hexo.extend.generator.register('timeline', function(locals) {
  const posts = locals.posts.sort('date', -1);
  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,
      tags: post.tags ? post.tags.toArray() : []
    });
  });
  
  return {
    path: 'timeline/index.html',
    layout: 'timeline',
    data: {
      title: '时间轴',
      timeline: timeline,
      years: Object.keys(timeline).sort((a, b) => b - a)
    }
  };
});

// themes/your-theme/scripts/best-practices.js

// ✅ 好的做法：使用命名空间避免冲突
hexo.extend.helper.register('mytheme_utils', function() {
  return {
    formatDate: (date) => date.format('YYYY-MM-DD'),
    truncate: (text, length) => text.substring(0, length) + '...',
    // 更多工具函数...
  };
});

// ❌ 避免：污染全局作用域
hexo.extend.filter.register('template_locals', function(locals) {
  // 不要这样做
  global.myCustomData = 'some data';
  return locals;
});

// ✅ 好的做法：在 locals 中添加命名空间的数据
hexo.extend.filter.register('template_locals', function(locals) {
  locals.mytheme = {
    version: '1.0.0',
    features: ['dark-mode', 'search', 'toc'],
    custom_data: 'some data'
  };
  return locals;
});

// ✅ 好的做法：根据页面类型有条件地添加数据
hexo.extend.filter.register('template_locals', function(locals) {
  // 只在需要的页面添加重量级数据
  if (locals.page.need_heavy_data) {
    locals.heavy_data = computeExpensiveData();
  }
  return locals;
});

// ✅ 好的做法：缓存计算结果
const cache = new Map();

hexo.extend.helper.register('expensive_calculation', function() {
  const cacheKey = 'my_calculation';
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const result = performExpensiveCalculation();
  cache.set(cacheKey, result);
  
  return result;
});

// themes/your-theme/scripts/custom-route.js
hexo.extend.generator.register('custom-page', function(locals) {
  return {
    path: 'custom-page/index.html',
    data: locals.posts,
    layout: 'custom-layout'
  };
});

hexo.extend.generator.register('author-pages', function(locals) {
  const authors = new Set();
  
  // 收集所有作者
  locals.posts.forEach(post => {
    if (post.author) authors.add(post.author);
  });
  
  // 为每个作者生成页面
  return Array.from(authors).map(author => ({
    path: `author/${author}/index.html`,
    data: {
      author: author,
      posts: locals.posts.filter(p => p.author === author)
    },
    layout: 'author'
  }));
});

// 高优先级路由（先匹配）
hexo.route.set('special-page.html', function() {
  return 'Special content';
});

// 普通路由
hexo.extend.generator.register('normal-generator', function(locals) {
  // 生成逻辑
});

hexo.source    // source 文件夹
hexo.theme     // themes/主题名 文件夹
hexo.public    // public 文件夹

// 处理 Markdown 文件
hexo.extend.processor.register('posts/:slug.md', function(file) {
  const data = {
    title: file.data.title,
    date: file.data.date,
    content: file.content
  };
  
  return data;
});

// 处理自定义文件类型
hexo.extend.processor.register('data/**/*.json', function(file) {
  // 处理 JSON 数据文件
  const jsonData = JSON.parse(file.content);
  return processCustomData(jsonData);
});

hexo.source.on('processAfter', function(file) {
  console.log('文件处理完成:', file.path);
});

hexo.source.on('processBefore', function(file) {
  console.log('准备处理文件:', file.path);
});

// scripts/custom-box.js
const Box = require('hexo-fs');

hexo.extend.processor.register('_data/**/*.yml', function(file) {
  const name = file.path.replace(/^_data\//, '').replace(/\.yml$/, '');
  
  hexo.locals.set(name, () => {
    return hexo.render.render({
      path: file.source,
      engine: 'yaml'
    });
  });
});

// Markdown 渲染器（默认）
hexo.config.markdown = {
  preset: 'default',
  render: {
    html: true,
    breaks: true
  }
};

// EJS 模板渲染器
// 直接在 .ejs 文件中使用

// Stylus 样式渲染器
hexo.config.stylus = {
  compress: true
};

// 注册 Pug 渲染器
hexo.extend.renderer.register('pug', 'html', function(data, options) {
  const pug = require('pug');
  return pug.compile(data.text)(options);
}, true);

// 注册自定义 Markdown 扩展
hexo.extend.renderer.register('md', 'html', function(data, options) {
  const marked = require('marked');
  
  // 自定义渲染规则
  const renderer = new marked.Renderer();
  renderer.heading = function(text, level) {
    return `<h${level} class="custom-heading">${text}</h${level}>`;
  };
  
  return marked(data.text, { renderer });
}, true);

// 手动触发渲染
hexo.render.render({
  text: '# Hello World',
  engine: 'markdown'
}).then(result => {
  console.log(result); // <h1>Hello World</h1>
});

// 渲染文件
hexo.render.render({
  path: 'path/to/file.md'
}).then(result => {
  // 渲染结果
});

// themes/your-theme/scripts/renderer-config.js
hexo.on('ready', function() {
  // 配置代码高亮
  hexo.config.highlight = {
    enable: true,
    line_number: true,
    auto_detect: true,
    tab_replace: '  ',
    wrap: true,
    hljs: false
  };
  
  // 配置 Markdown 渲染选项
  hexo.config.marked = {
    gfm: true,
    pedantic: false,
    breaks: true,
    smartLists: true,
    smartypants: true
  };
});

// 文章对象的主要属性
{
  title: '文章标题',
  date: Date,          // 发布日期
  updated: Date,       // 更新日期
  comments: true,      // 是否开启评论
  layout: 'post',      // 布局类型
  content: '...',      // 文章内容（HTML）
  excerpt: '...',      // 文章摘要
  more: '...',         // "阅读更多"后的内容
  source: '...',       // 源文件路径
  full_source: '...',  // 完整源文件路径
  path: '...',         // 文章URL路径
  permalink: '...',    // 完整URL
  categories: [],      // 分类
  tags: [],           // 标签
  photos: [],         // 相册
  link: '',           // 外部链接
  raw: '',            // 原始内容（Markdown）
  published: true,    // 是否发布
  _content: '...',    // 原始内容
  _id: '...'          // 唯一标识
}

// scripts/scaffold-generator.js
hexo.extend.filter.register('new_post_path', function(data, replace) {
  // 根据分类自动组织文件路径
  if (data.categories && data.categories.length > 0) {
    const category = data.categories[0];
    return `source/_posts/${category}/${data.slug}.md`;
  }
  return data.path;
});

// 自动添加默认 Front-matter
hexo.extend.filter.register('before_post_render', function(data) {
  if (!data.author) {
    data.author = this.config.author;
  }
  if (!data.cover) {
    data.cover = '/images/default-cover.jpg';
  }
  return data;
});

// themes/your-theme/scripts/reading-time.js

/**
 * 功能：计算文章阅读时间并生成阅读统计页面
 * 涉及概念：事件、本地变量、路由、Box、渲染、文章
 */

// 1. 注册 Helper（本地变量扩展）
hexo.extend.helper.register('reading_time', function(content) {
  const wordsPerMinute = 200;
  const words = content.replace(/<[^>]+>/g, '').split(/\s+/).length;
  const minutes = Math.ceil(words / wordsPerMinute);
  return minutes;
});

// 2. 在文章处理时添加阅读时间（事件 + Box）
hexo.extend.filter.register('before_post_render', function(data) {
  if (data.content) {
    const readingTime = this.extend.helper.get('reading_time').bind(this)(data.content);
    data.reading_time = readingTime;
  }
  return data;
});

// 3. 创建阅读统计路由（路由系统）
hexo.extend.generator.register('reading-stats', function(locals) {
  const posts = locals.posts.sort('date', -1);
  const stats = {
    total_posts: posts.length,
    total_reading_time: 0,
    avg_reading_time: 0,
    posts_by_time: []
  };
  
  posts.forEach(post => {
    if (post.reading_time) {
      stats.total_reading_time += post.reading_time;
      stats.posts_by_time.push({
        title: post.title,
        path: post.path,
        reading_time: post.reading_time
      });
    }
  });
  
  stats.avg_reading_time = Math.ceil(stats.total_reading_time / stats.total_posts);
  
  return {
    path: 'reading-stats/index.html',
    data: stats,
    layout: 'reading-stats'
  };
});

// 4. 在生成后输出统计信息（事件）
hexo.on('generateAfter', function() {
  const posts = this.locals.get('posts');
  const totalTime = posts.reduce((sum, post) => sum + (post.reading_time || 0), 0);
  console.log(`📚 总计 ${posts.length} 篇文章，预计阅读时间 ${totalTime} 分钟`);
});