我第一次尝试给静态站点加入 AI 内容生成功能时，折腾了整整三天。Eleventy 搭配 AI API 的配置看起来简单，但新人很容易在环境变量、依赖版本、接口地址上踩坑。今天我把完整的踩坑经验整理成这篇教程，手把手带你从零开始搭建属于你的 AI 增强博客系统。

为什么选择 Eleventy + AI 内容生成？

Eleventy（简称 11ty）是我用过最纯粹的静态站点生成器。它没有 React 的复杂依赖，也没有 Gatsby 的过度封装，模板引擎支持 Nunjucks、Liquid、EJS 等十几种选择。对于想要轻量化接入 AI 能力的开发者来说，Eleventy 是绝佳的起点。

通过 AI API，我们可以实现：文章摘要自动生成、标签智能推荐、内容相似度匹配、多语言翻译等功能。我在个人博客上实现了文章自动摘要生成，将原本需要手动撰写摘要的时间从每篇 10 分钟缩短到 0 秒。

第一步：注册 HolySheep AI 并获取 API Key

在开始之前，你需要准备一个 AI API 服务。我强烈推荐使用 立即注册 HolySheep AI，原因很简单：

注册完成后，在控制台复制你的 API Key，格式类似 YOUR_HOLYSHEEP_API_KEY，这个密钥后续会用到。

第二步：搭建 Eleventy 项目环境

我假设你已经安装了 Node.js（v18 及以上版本）。打开终端，执行以下命令创建项目：

mkdir eleventy-ai-blog && cd eleventy-ai-blog
npm init -y
npm install --save-dev @11ty/eleventy
npm install dotenv openai

项目结构建议如下：

eleventy-ai-blog/
├── .env                 # 环境变量配置
├── .eleventy.js         # Eleventy 配置文件
├── src/
│   ├── _data/           # 全局数据文件
│   │   └── site.js
│   ├── _includes/       # 模板组件
│   ├── posts/           # 博客文章
│   └── index.njk        # 首页模板
└── package.json

第三步：配置环境变量和 API 连接

在项目根目录创建 .env 文件，注意这个文件不要提交到版本库（添加到 .gitignore）：

HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY
HOLYSHEEP_BASE_URL=https://api.holysheep.ai/v1

然后在 .eleventy.js 中配置 Eleventy 的 AI 数据生成功能：

require('dotenv').config();
const OpenAI = require('openai');

module.exports = function(eleventyConfig) {
    // 初始化 HolySheep AI 客户端
    const holysheepClient = new OpenAI({
        apiKey: process.env.HOLYSHEEP_API_KEY,
        baseURL: process.env.HOLYSHEEP_BASE_URL
    });
    
    // 注册全局数据，用于在模板中访问 AI 功能
    eleventyConfig.addGlobalData('ai', {
        client: holysheepClient,
        
        // 生成文章摘要
        async generateSummary(content) {
            const response = await this.client.chat.completions.create({
                model: 'gpt-4.1',
                messages: [{
                    role: 'system',
                    content: '你是一个专业的内容编辑，擅长生成简洁准确的文章摘要。'
                }, {
                    role: 'user',
                    content: 请为以下文章生成一段50字以内的摘要：\n\n${content}
                }],
                max_tokens: 100,
                temperature: 0.3
            });
            return response.choices[0].message.content;
        },
        
        // 推荐标签
        async recommendTags(content) {
            const response = await this.client.chat.completions.create({
                model: 'gpt-4.1',
                messages: [{
                    role: 'system',
                    content: '你是一个专业的标签推荐专家，返回JSON数组格式的标签列表，最多5个标签。'
                }, {
                    role: 'user',
                    content: 分析以下内容，推荐最合适的标签（返回JSON数组）：\n\n${content}
                }],
                max_tokens: 50,
                temperature: 0.5
            });
            try {
                return JSON.parse(response.choices[0].message.content);
            } catch {
                return ['技术', '教程'];
            }
        }
    });
    
    return {
        dir: {
            input: 'src',
            output: '_site',
            includes: '_includes',
            data: '_data'
        },
        markdownTemplateEngine: 'njk',
        htmlTemplateEngine: 'njk'
    };
};

第四步：创建文章处理模板

在 src/posts/ 目录下创建一篇示例文章 first-post.md：

---
title: 我的第一篇AI增强博客文章
date: 2024-01-15
layout: post.njk
---

Eleventy与AI的完美结合


本文将介绍如何使用Eleventy静态站点生成器配合AI API实现智能化内容处理。我们会实现自动摘要生成、标签推荐等功能。

Eleventy是一个轻量级的静态站点生成器，它没有复杂的依赖，非常适合想要快速搭建博客的开发者。通过本文的学习，你将掌握如何将AI能力集成到Eleventy项目中。


为什么选择Eleventy


Eleventy的核心优势在于其简洁性和灵活性。与Gatsby、Jekyll等工具相比，Eleventy不会强制你使用特定的JavaScript框架。它的模板引擎支持Nunjucks、Liquid、EJS等多种选择。


AI集成的价值


通过AI API，我们可以自动生成文章摘要、推荐标签、甚至实现多语言翻译。这大大提升了内容创作的效率。


实战经验


我在搭建这个博客系统时，最初遇到了API调用超时和token计算错误的问题。后来发现是因为没有正确配置baseURL参数，导致请求被发送到了错误的地址。使用HolySheheep AI后，国内直连的延迟保持在50ms以内，体验非常流畅。

创建 src/_includes/layouts/post.njk 布局文件：

---
layout: base.njk
---
<article class="post">
    <h1>{{ title }}</h1>
    <time>{{ date | htmlDateString }}</time>
    
    {% if tags %}
    <div class="tags">
        {% for tag in tags %}
        <span class="tag">{{ tag }}</span>
        {% endfor %}
    </div>
    {% endif %}
    
    <div class="content">
        {{ content | safe }}
    </div>
    
    {% if page.summary %}
    <div class="summary">
        <h2>文章摘要</h2>
        <p>{{ page.summary }}</p>
    </div>
    {% endif %}
</article>

第五步：实现自动化内容处理

创建 src/posts/posts.json 配置文件，定义文章的全局数据处理逻辑：

{
    "layout": "post.njk",
    "tags": ["posts"],
    "permalink": "/posts/{{ page.fileSlug }}/index.html"
}

在实际项目中，我通常会在构建时调用 AI 生成元数据。在 .eleventy.js 中添加一个预处理函数：

eleventyConfig.on('eleventy.before', async ({ dir }) => {
    console.log('开始 AI 内容处理流程...');
});

eleventyConfig.addShortcode('aiSummary', async function(content) {
    try {
        const summary = await eleventyConfig.globalData.ai.generateSummary(content);
        return summary;
    } catch (error) {
        console.error('AI 摘要生成失败:', error.message);
        return '摘要生成失败，请稍后重试';
    }
});

eleventyConfig.addShortcode('aiTags', async function(content) {
    try {
        const tags = await eleventyConfig.globalData.ai.recommendTags(content);
        return tags.join(', ');
    } catch (error) {
        console.error('AI 标签推荐失败:', error.message);
        return 'AI, 技术, 教程';
    }
});

常见报错排查

在我配置 Eleventy AI 集成的过程中，遇到了几个高频错误，这里整理出来帮你避坑。

错误一：API Key 未定义或格式错误

错误信息：Error: The apiKey and baseURL options are required to use the OpenAI SDK

原因分析：环境变量未正确加载，或者 .env 文件格式问题。

解决方案：确保在项目根目录存在 .env 文件，且使用正确的格式加载：

// 方案1：使用 dotenv 手动加载
require('dotenv').config({ path: '.env' });

// 方案2：检查 .env 文件格式（不要有空格）
HOLYSHEEP_API_KEY=sk-holysheep-xxxxx
HOLYSHEEP_BASE_URL=https://api.holysheep.ai/v1

// 方案3：在终端中导出环境变量（临时方案）
export HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY
export HOLYSHEEP_BASE_URL=https://api.holysheep.ai/v1

错误二：请求超时或网络连接失败

错误信息：Error: Connection timeout exceeded 30000ms 或 Error: getaddrinfo ENOTFOUND api.openai.com

原因分析：baseURL 配置错误导致请求发到了错误的地址，或者网络环境不稳定。

解决方案：

// 正确配置 HolySheheep API
const holysheepClient = new OpenAI({
    apiKey: process.env.HOLYSHEEP_API_KEY,
    baseURL: 'https://api.holysheep.ai/v1',  // 必须是完整路径
    timeout: 60000,  // 超时时间设为60秒
    maxRetries: 3    // 自动重试3次
});

// 添加请求拦截器处理超时
holysheepClient.maxRetries = 3;
holysheepClient.timeout = 60000;

错误三：Token 计算错误导致预算超支

错误信息：实际消耗的 tokens 远超预期。

原因分析：没有正确计算输入 tokens，或者重复发送了相同的内容。

解决方案：

// 使用 tiktoken 库准确计算 tokens
const encoding = require('tiktok');

function calculateTokens(text) {
    const enc = encoding.get_encoding('cl100k_base');
    return enc.encode(text).length;
}

// 在调用 AI 之前估算成本
async function aiGenerateWithBudgetCheck(content, maxTokens = 100) {
    const inputTokens = calculateTokens(content);
    const estimatedCost = (inputTokens + maxTokens) / 1_000_000 * 8; // GPT-4.1 = $8/MTok
    
    console.log(预估输入 tokens: ${inputTokens});
    console.log(预估成本: $${estimatedCost.toFixed(4)});
    
    if (estimatedCost > 0.1) {
        console.warn('单次请求成本较高，建议优化内容长度');
    }
    
    return await holysheepClient.chat.completions.create({
        model: 'gpt-4.1',
        messages: [{ role: 'user', content }],
        max_tokens: maxTokens
    });
}

错误四：模板渲染时异步函数未正确处理

错误信息：Error: Cannot read properties of undefined (reading 'generateSummary')

原因分析：在 Nunjucks 模板中直接调用异步函数，但模板引擎是同步渲染的。

解决方案：使用 Eleventy 的异步过滤器和生命周期钩子：

// 在 .eleventy.js 中注册异步过滤器
eleventyConfig.addFilter('asyncSummary', async function(content) {
    try {
        return await holysheepClient.chat.completions.create({
            model: 'gpt-4.1',
            messages: [{
                role: 'system',
                content: '生成简洁摘要'
            }, {
                role: 'user',
                content: content
            }],
            max_tokens: 100
        }).then(res => res.choices[0].message.content);
    } catch (e) {
        return '摘要加载中...';
    }
});

// 在模板中使用
// {{ postContent | asyncSummary }}

实战经验总结

我最初配置这套系统时，最头疼的是构建性能问题。每次修改内容都会触发 AI API 调用，导致开发体验很差。后来我改用了增量构建策略：只有新文章才调用 AI 生成摘要，已有的摘要直接读取缓存。

// 添加缓存机制
const fs = require('fs');
const path = require('path');

const cacheDir = '.ai-cache';
if (!fs.existsSync(cacheDir)) {
    fs.mkdirSync(cacheDir, { recursive: true });
}

async function getCachedSummary(fileSlug, content) {
    const cacheFile = path.join(cacheDir, ${fileSlug}.json);
    
    // 缓存存在则直接读取
    if (fs.existsSync(cacheFile)) {
        const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
        // 内容没变则使用缓存
        if (cached.contentHash === hashContent(content)) {
            return cached.summary;
        }
    }
    
    // 生成新摘要
    const summary = await holysheepClient.chat.completions.create({
        model: 'gpt-4.1',
        messages: [{ role: 'user', content: 摘要：${content.slice(0, 1000)} }],
        max_tokens: 100
    }).then(res => res.choices[0].message.content);
    
    // 保存缓存
    fs.writeFileSync(cacheFile, JSON.stringify({
        contentHash: hashContent(content),
        summary,
        updated: new Date().toISOString()
    }));
    
    return summary;
}

function hashContent(content) {
    const crypto = require('crypto');
    return crypto.createHash('md5').update(content).digest('hex');
}

另一个经验是关于成本控制。使用 DeepSeek V3.2 模型时，成本仅为 GPT-4.1 的 5%（$0.42 vs $8/MTok），对于摘要生成这类简单任务，完全没必要使用昂贵的模型。

成本对比与推荐

根据 2026 年主流模型 output 价格，我的使用建议是：

使用 HolySheheep AI 的最大感受是成本透明可控。充值后立即到账，API 调用明细清晰可查，对于预算敏感的独立开发者来说非常友好。

进阶功能拓展

掌握基础配置后，你可以尝试以下高级功能：

我的博客目前集成了摘要生成和标签推荐两个功能，每周节省约 2 小时的重复性工作。如果你想了解更多进阶玩法，可以参考 Eleventy 官方文档和 HolySheheep AI 的 API 指南。

总结

Eleventy 搭配 AI 内容生成是一个强大的组合，特别适合技术博客和文档站点。通过本文的步骤，你应该能够：

如果遇到任何问题，欢迎在评论区留言。记住，使用 AI 工具时一定要关注成本和调用频率，合理使用缓存和模型选择可以大幅节省开支。

👉 免费注册 HolySheheep AI，获取首月赠额度

```

相关资源

相关文章