如何用JavaScript从零实现一个静态站点博客生成器？

静态站点生成的概念并不新鲜，但用JavaScript亲手实现一个博客生成器，能让你彻底理解内容与展示分离的构建思想。整个过程可以概括为：把Markdown格式的文章作为数据源，通过Node.js脚本读取和解析这些文件，再结合模板引擎生成一批纯静态的HTML页面。相比动态博客系统，静态站点不需要数据库和服务器端运行环境，访问速度快，部署也极其简单。

静态站点生成的基本流程

一个静态博客生成器通常包含四个核心步骤：读取源文件、解析元数据与正文、套用模板渲染、输出最终HTML。源文件一般是Markdown文档，每篇文章开头可以包含一段YAML格式的Front Matter，用来声明标题、日期、标签等信息。解析阶段需要把Front Matter和正文分离，并把Markdown转换成HTML片段。模板渲染阶段把这些片段注入到页面骨架中，生成完整的HTML文档。输出阶段按照一定的目录结构写入磁盘，例如文章页放在 posts 目录下，首页和归档页放在根目录。

目录结构的设计直接影响后续的URL生成和部署。常见做法是把所有Markdown源文件放在 content 或 posts 文件夹中，静态资源放在 public 或 assets 文件夹中，模板文件放在 templates 文件夹中，构建脚本 build.js 放在项目根目录。构建完成后生成一个 dist 或 public 输出目录，里面就是可以直接上传到静态服务器的文件。下面是一个典型项目的目录示例。

my-blog/
├── content/
│   ├── first-post.md
│   └── second-post.md
├── templates/
│   ├── index.ejs
│   ├── post.ejs
│   └── tag.ejs
├── public/
│   └── style.css
├── build.js
└── package.json

这个结构把内容、模板和构建逻辑清晰分离。内容创作者只需要关心 content 目录下的Markdown文件，前端样式放在 public 目录，而构建脚本负责把两者结合起来。这样做的好处是，即使以后更换模板引擎或调整站点样式，内容文件几乎不需要改动。

用Node.js解析Markdown与Front Matter

Node.js的标准库提供了 fs 和 path 模块，可以方便地遍历目录和读写文件。解析Front Matter最常用的第三方库是 gray-matter，它可以自动识别YAML格式的元数据块，并返回一个包含 data 和 content 的对象。Markdown解析可以选择 marked 或 markdown-it，前者速度快、API简洁，后者插件生态更丰富，支持更精细的语法扩展。

如果不希望引入太多依赖，也可以自己写一个简单的Front Matter解析器。Front Matter通常被包裹在两个 --- 之间，位于文件开头。可以用正则表达式提取这部分内容，再用一个简单的YAML解析函数处理键值对。下面是一个使用 gray-matter 和 marked 的完整示例。

const fs = require('fs');
const path = require('path');
const matter = require('gray-matter');
const marked = require('marked');

function parsePost(filePath) {
  const raw = fs.readFileSync(filePath, 'utf8');
  const parsed = matter(raw);
  const html = marked.parse(parsed.content);
  return {
    title: parsed.data.title || 'Untitled',
    date: parsed.data.date || new Date().toISOString(),
    tags: parsed.data.tags || [],
    content: html,
    slug: path.basename(filePath, '.md')
  };
}

const post = parsePost('content/first-post.md');
console.log(post.title);
console.log(post.tags);

这段代码展示了最基本的解析流程。gray-matter 会把Front Matter中的 title、date、tags 等字段提取到 data 对象中，正文通过 marked.parse 转成HTML。slug 字段用于生成文章页的URL，通常直接使用文件名去掉扩展名。实际项目中还需要处理编码问题、文件不存在异常以及更复杂的Front Matter类型，但核心逻辑就是这样。

解析完所有文章后，需要把它们组织成适合渲染的数据结构。通常会生成一个包含所有文章元数据的数组，并按日期倒序排列，首页和归档页可以复用这个数组。标签页则需要统计所有标签及其对应的文章列表。这些中间数据可以缓存在内存中，避免重复读取文件。

模板渲染与页面生成

模板引擎的选择会影响代码的编写方式。EJS 的语法接近原生HTML，使用 <% %> 嵌入JavaScript逻辑，学习成本低。Handlebars 的逻辑更受限，但模板更纯粹。对于博客系统来说，EJS 足够灵活，可以直接在模板中遍历文章数组、判断条件。下面是一个首页模板的示例。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>我的博客</title>
</head>
<body>
  <h1>最新文章</h1>
  <ul>
    <% posts.forEach(function(post) { %>
      <li>
        <a href="/posts/<%= post.slug %>.html"><%= post.title %></a>
        <span><%= post.date %></span>
      </li>
    <% }) %>
  </ul>
</body>
</html>

注意代码块中的HTML标签已经转义，以保证在页面上正确显示。模板中使用了 EJS 的 <% %> 语法来执行遍历和输出变量。渲染时，把 posts 数组作为数据传入模板引擎，就会生成对应的HTML字符串。文章页模板类似，根据 slug 找到对应文章，输出标题、日期和正文内容。

生成页面时，需要确定输出路径。一般将文章页输出到 posts/ 目录下，文件名为 slug.html。首页输出为 index.html，标签页可以输出到 tags/ 目录下，每个标签生成一个文件，或者使用查询参数。如果把所有标签放在一个页面，可以用锚点链接定位。这里推荐为每个标签生成独立页面，有利于SEO。生成逻辑可以用循环和 fs.mkdirSync 创建目录，再用 fs.writeFileSync 写入HTML。

构建脚本的整合与部署优化

把前面的解析和渲染步骤整合到一个 build.js 中，就可以在命令行执行 node build.js 一键生成整个站点。构建脚本的流程包括：清空输出目录、读取所有Markdown文件、解析并排序、渲染首页和文章页、渲染标签页、复制静态资源。下面是一个精简但可运行的构建脚本。

const fs = require('fs');
const path = require('path');
const matter = require('gray-matter');
const marked = require('marked');
const ejs = require('ejs');

const CONTENT_DIR = path.join(__dirname, 'content');
const TEMPLATE_DIR = path.join(__dirname, 'templates');
const OUTPUT_DIR = path.join(__dirname, 'dist');

function build() {
  if (fs.existsSync(OUTPUT_DIR)) {
    fs.rmSync(OUTPUT_DIR, { recursive: true, force: true });
  }
  fs.mkdirSync(OUTPUT_DIR, { recursive: true });

  const files = fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.md'));
  const posts = files.map(file => {
    const raw = fs.readFileSync(path.join(CONTENT_DIR, file), 'utf8');
    const parsed = matter(raw);
    return {
      title: parsed.data.title || 'Untitled',
      date: parsed.data.date || new Date().toISOString(),
      tags: parsed.data.tags || [],
      content: marked.parse(parsed.content),
      slug: path.basename(file, '.md')
    };
  }).sort((a, b) => new Date(b.date) - new Date(a.date));

  const indexTemplate = fs.readFileSync(path.join(TEMPLATE_DIR, 'index.ejs'), 'utf8');
  const postTemplate = fs.readFileSync(path.join(TEMPLATE_DIR, 'post.ejs'), 'utf8');
  const tagTemplate = fs.readFileSync(path.join(TEMPLATE_DIR, 'tag.ejs'), 'utf8');

  const indexHtml = ejs.render(indexTemplate, { posts: posts });
  fs.writeFileSync(path.join(OUTPUT_DIR, 'index.html'), indexHtml);

  fs.mkdirSync(path.join(OUTPUT_DIR, 'posts'), { recursive: true });
  posts.forEach(post => {
    const html = ejs.render(postTemplate, { post: post });
    fs.writeFileSync(path.join(OUTPUT_DIR, 'posts', post.slug + '.html'), html);
  });

  const tagMap = new Map();
  posts.forEach(post => {
    post.tags.forEach(tag => {
      if (!tagMap.has(tag)) tagMap.set(tag, []);
      tagMap.get(tag).push(post);
    });
  });
  fs.mkdirSync(path.join(OUTPUT_DIR, 'tags'), { recursive: true });
  tagMap.forEach((tagPosts, tag) => {
    const html = ejs.render(tagTemplate, { tag: tag, posts: tagPosts });
    fs.writeFileSync(path.join(OUTPUT_DIR, 'tags', tag + '.html'), html);
  });

  const publicDir = path.join(__dirname, 'public');
  if (fs.existsSync(publicDir)) {
    fs.cpSync(publicDir, OUTPUT_DIR, { recursive: true });
  }
  console.log('Build completed. Output directory: ' + OUTPUT_DIR);
}

build();

这个脚本展示了完整的构建流程。它首先清空输出目录避免残留文件，然后读取所有Markdown文件并解析元数据，按日期排序。接着渲染首页、文章页和标签页，最后把 public 目录下的静态资源复制到输出目录。实际使用时可以把配置提取到单独的 config.js 文件，支持自定义站点标题、作者等信息。

部署静态站点非常灵活。可以把生成的 dist 目录上传到 GitHub Pages、Netlify、Vercel 或任何静态服务器。为了提升访问速度，可以配置CDN和缓存策略。由于所有页面都是静态文件，服务器不需要执行任何代码，安全性也更高。如果博客文章数量很多，可以考虑在构建时生成RSS订阅源和 sitemap.xml，帮助搜索引擎收录。

静态站点生成JavaScript博客系统修改时间：2026-10-03 22:10:08