Hexo 博客Algolia搜索索引自动上传脚本使用指南

前言

在配置 Hexo Butterfly 主题的 Algolia 搜索功能时，每次发布新文章或更新内容后，都需要手动执行命令上传搜索索引。这个过程繁琐且容易出错：

• ❌ 需要记住复杂的环境变量设置命令
• ❌ 每次都要输入 Admin API Key
• ❌ 容易忘记上传索引导致搜索不到新文章
• ❌ 出错时难以快速定位问题

为了简化这个流程，我编写了一个 PowerShell 自动上传脚本，只需一条命令即可完成索引上传，并提供友好的提示信息。

一、什么是 Algolia 搜索？

Algolia 简介

Algolia 是一个强大的搜索即服务（Search-as-a-Service）平台，具有以下特点：

• ⚡ 极速搜索：毫秒级响应速度
• 🎯 智能匹配：支持拼写纠错、同义词、高亮显示
• 🌍 全球 CDN：全球分布式架构，低延迟
• 📊 搜索分析：提供详细的搜索数据分析
• 🆓 免费额度：每月 10,000 次搜索请求免费

为什么选择 Algolia？

相比 Hexo 默认的本地搜索，Algolia 有明显优势：

特性	本地搜索	Algolia 搜索
搜索速度	慢（需下载全部数据）	极快（云端索引）
文件大小	随文章增加而增大	无影响
搜索质量	基础	智能模糊匹配
移动端体验	较差	优秀
搜索分析	无	详细数据

二、问题与解决方案

传统上传方式的痛点

在没有脚本之前，上传 Algolia 索引需要这样操作：

# 1. 设置环境变量（每次都要输入）
$env:HEXO_ALGOLIA_INDEXING_KEY="your_admin_api_key_here"

# 2. 执行上传命令
hexo algolia

# 3. 查看输出，判断是否成功
# 4. 如果失败，手动排查问题...

存在的问题：

1. ⚠️ 容易打错 API Key：32 位的 API Key 手动输入容易出错
2. ⚠️ 环境变量临时性：关闭 PowerShell 后失效，下次还要重新设置
3. ⚠️ 错误提示不明确：出错时难以快速定位问题
4. ⚠️ 忘记执行：发布文章后忘记上传索引，导致搜索不到新内容

脚本化解决方案

通过 PowerShell 脚本，我们可以：

✅ 一键执行：运行 .\upload-algolia.ps1 即可
✅ 自动设置环境变量：无需手动输入 API Key
✅ 友好的提示信息：清晰的执行状态和错误提示
✅ 智能错误处理：根据执行结果提供针对性建议

三、脚本详解

完整脚本代码

# Algolia Upload Script
# Usage: .\upload-algolia.ps1

Write-Host "[INFO] Starting Algolia index upload..." -ForegroundColor Green

# Set Admin API Key (must match apiKey in _config.yml)
$env:HEXO_ALGOLIA_INDEXING_KEY="xxxxxxxxxxxxxxxxxxxxxxxxx"

# Upload index
Write-Host "[INFO] Uploading articles to Algolia..." -ForegroundColor Yellow
hexo algolia

if ($LASTEXITCODE -eq 0) {
    Write-Host ""
    Write-Host "[SUCCESS] Upload completed!" -ForegroundColor Green
    Write-Host ""
    Write-Host "Next steps:" -ForegroundColor Cyan
    Write-Host "  1. Run: hexo cl" -ForegroundColor White
    Write-Host "  2. Run: hexo g" -ForegroundColor White
    Write-Host "  3. Run: hexo s" -ForegroundColor White
    Write-Host "  4. Test search function on your website" -ForegroundColor White
} else {
    Write-Host ""
    Write-Host "[ERROR] Upload failed!" -ForegroundColor Red
    Write-Host ""
    Write-Host "Please check:" -ForegroundColor Yellow
    Write-Host "  1. Application ID is correct" -ForegroundColor White
    Write-Host "  2. Admin API Key is correct (must have write permission)" -ForegroundColor White
    Write-Host "  3. Index 'hexo' exists in Algolia dashboard" -ForegroundColor White
    Write-Host "  4. API Key has 'addObject', 'deleteObject', 'editSettings' permissions" -ForegroundColor White
}

代码逐行解析

1. 脚本说明（第 1-2 行）

# Algolia Upload Script
# Usage: .\upload-algolia.ps1

• 注释说明脚本用途和使用方法
• 帮助其他人或未来的自己快速理解脚本功能

2. 开始提示（第 4 行）

Write-Host "[INFO] Starting Algolia index upload..." -ForegroundColor Green

• 使用 Write-Host 输出彩色文本
• -ForegroundColor Green：绿色表示开始执行
• [INFO] 标签：统一的日志格式

3. 设置环境变量（第 6-7 行）

# Set Admin API Key (must match apiKey in _config.yml)
$env:HEXO_ALGOLIA_INDEXING_KEY="xxxxxxxxxxxxxxxxxxxxxxx"

关键点：

• $env: 是 PowerShell 中设置环境变量的语法
• HEXO_ALGOLIA_INDEXING_KEY 是 hexo-algolia 插件要求的环境变量名
• 值必须与 _config.yml 中的 algolia.apiKey 一致
• ⚠️ 注意：这里使用的是 Admin API Key，不是 Search-Only API Key

4. 执行上传（第 9-10 行）

# Upload index
Write-Host "[INFO] Uploading articles to Algolia..." -ForegroundColor Yellow
hexo algolia

• 黄色提示表示正在执行操作
• hexo algolia 是 hexo-algolia 插件提供的命令
• 该命令会读取所有文章并上传到 Algolia

5. 判断执行结果（第 12-31 行）

if ($LASTEXITCODE -eq 0) {
    # 成功的处理逻辑
} else {
    # 失败的处理逻辑
}

核心变量：$LASTEXITCODE

• PowerShell 的内置变量
• 保存上一条命令的退出代码
• 0 表示成功，非 0 表示失败

6. 成功提示（第 13-21 行）

Write-Host ""
Write-Host "[SUCCESS] Upload completed!" -ForegroundColor Green
Write-Host ""
Write-Host "Next steps:" -ForegroundColor Cyan
Write-Host "  1. Run: hexo cl" -ForegroundColor White
Write-Host "  2. Run: hexo g" -ForegroundColor White
Write-Host "  3. Run: hexo s" -ForegroundColor White
Write-Host "  4. Test search function on your website" -ForegroundColor White

设计理念：

• ✅ 明确告知用户操作成功
• 📋 提供后续操作步骤
• 🎨 使用不同颜色增强可读性

7. 失败提示（第 22-31 行）

Write-Host ""
Write-Host "[ERROR] Upload failed!" -ForegroundColor Red
Write-Host ""
Write-Host "Please check:" -ForegroundColor Yellow
Write-Host "  1. Application ID is correct" -ForegroundColor White
Write-Host "  2. Admin API Key is correct (must have write permission)" -ForegroundColor White
Write-Host "  3. Index 'hexo' exists in Algolia dashboard" -ForegroundColor White
Write-Host "  4. API Key has 'addObject', 'deleteObject', 'editSettings' permissions" -ForegroundColor White

故障排查清单：

1. Application ID：检查是否正确
2. Admin API Key：确认有写入权限
3. 索引名称：确认 hexo 索引已创建
4. API 权限：确认 Key 有必要的操作权限

四、使用教程

前置条件

在使用脚本之前，需要完成以下配置：

1. 安装 hexo-algolia 插件

npm install hexo-algolia --save

2. 配置 Algolia 账号

在 _config.yml 中添加：

# Algolia Search Configuration
algolia:
  applicationID: 'eeeeeee'                        # 你的 Application ID
  apiKey: 'xxxxxxxxxxxxxxxxxxxxxxx'         # Admin API Key
  indexName: 'hexo'                                  # 索引名称
  fields:
    - title           # 文章标题
    - date            # 发布日期
    - slug            # 文章路径
    - excerpt         # 文章摘要
    - content:strip   # 文章全文内容（去除HTML标签）⚡ 关键配置！
    - tags            # 文章标签
    - categories      # 文章分类
  chunkSize: 5000     # 每个记录的最大字符数，避免超出Algolia限制

重要说明：

• 📌 content:strip：这是实现全文搜索的关键配置，会索引文章的完整内容
• 📌 chunkSize: 5000：限制每条记录大小，防止超出 Algolia 的 10KB 限制
• ⚠️ 不配置 fields：默认只会索引标题，导致搜索不到文章内容

获取 Algolia 配置：

1. 登录 Algolia Dashboard
2. 进入你的应用
3. Settings → API Keys
4. 复制以下信息：
   • Application ID
   • Admin API Key（⚠️ 不是 Search-Only API Key）
5. Indices → Create Index 创建名为 hexo 的索引

3. 启用 Algolia 搜索

在 _config.butterfly.yml 中配置：

# Algolia search
algolia_search:
  enable: true
  hits:
    per_page: 6

使用步骤

步骤 1：创建脚本文件

在博客根目录创建 upload-algolia.ps1 文件，复制完整脚本代码。

步骤 2：修改 API Key

将脚本中的 API Key 替换为你自己的：

$env:HEXO_ALGOLIA_INDEXING_KEY="你的_Admin_API_Key"

⚠️ 注意：

• 必须使用 Admin API Key
• 必须与 _config.yml 中的 apiKey 一致

步骤 3：运行脚本

打开 PowerShell，进入博客根目录：

# 进入博客目录
cd E:\blog\blog-demo

# 执行脚本
.\upload-algolia.ps1

步骤 4：查看执行结果

成功输出示例：

[INFO] Starting Algolia index upload...
[INFO] Uploading articles to Algolia...
INFO  [hexo-algolia] Testing HEXO_ALGOLIA_INDEXING_KEY permissions.
INFO  Start processing
INFO  [hexo-algolia] 34 records to index (post, page).
INFO  [hexo-algolia] Indexing chunk 1 of 1 (34 records)
INFO  [hexo-algolia] Indexing done.

[SUCCESS] Upload completed!

Next steps:
  1. Run: hexo cl
  2. Run: hexo g
  3. Run: hexo s
  4. Test search function on your website

失败输出示例：

[INFO] Starting Algolia index upload...
[INFO] Uploading articles to Algolia...
ERROR [hexo-algolia] Not enough rights to update an object

[ERROR] Upload failed!

Please check:
  1. Application ID is correct
  2. Admin API Key is correct (must have write permission)
  3. Index 'hexo' exists in Algolia dashboard
  4. API Key has 'addObject', 'deleteObject', 'editSettings' permissions

五、常见问题与解决方案

Q1：脚本无法执行，提示”未对文件进行数字签名”

错误信息：

.\upload-algolia.ps1 : 无法加载文件 E:\blog\blog-demo\upload-algolia.ps1。
未对文件 E:\blog\blog-demo\upload-algolia.ps1 进行数字签名。
无法在当前系统上运行该脚本。

原因：PowerShell 执行策略限制

解决方法：

# 临时允许执行（当前会话有效）
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

# 永久允许执行（需要管理员权限）
Set-ExecutionPolicy RemoteSigned

# 然后再运行脚本
.\upload-algolia.ps1

Q2：提示”Not enough rights to update an object”

原因：API Key 权限不足

解决步骤：

1. 检查是否使用 Admin API Key

   • ❌ Search-Only API Key（只读）
   • ✅ Admin API Key（可读写）

2. 在 Algolia Dashboard 中验证权限

   • 进入 Settings → API Keys
   • 找到你的 Admin API Key
   • 确认有以下权限：
     • ✅ addObject（添加对象）
     • ✅ deleteObject（删除对象）
     • ✅ editSettings（编辑设置）
     • ✅ listIndexes（列出索引）

3. 重新生成 API Key（如果需要）

   • 点击 All API Keys → New API Key
   • 选择所有必要权限
   • 选择索引：hexo
   • 复制新生成的 Key

Q3：能搜索到标题，但搜索不到文章内容

问题描述：搜索文章标题可以找到结果，但搜索文章正文内容却搜索不到。

原因：缺少 fields 配置，默认只索引标题

解决方法：

在 _config.yml 的 algolia 配置中添加 fields 字段：

algolia:
  applicationID: 'eeeeeee'
  apiKey: 'xxxxxxxxxxxxxxxxxxxxxxx'
  indexName: 'hexo'
  fields:
    - title
    - date
    - slug
    - excerpt
    - content:strip   # ⚡ 这是关键！索引文章全文
    - tags
    - categories
  chunkSize: 5000     # 防止内容过大

配置完成后，必须重新上传索引：

.\upload-algolia.ps1

验证方法：

1. 上传成功后，访问 Algolia Dashboard
2. 进入你的索引 → Browse
3. 随便点击一条记录，查看是否有 content 字段
4. 如果有内容，说明配置成功

Q4：索引上传成功，但搜索不到内容

可能原因及解决方法：

原因 1：前端配置的 API Key 错误

在 _config.butterfly.yml 中检查：

# Local search
local_search:
  enable: false  # ← 确保本地搜索已关闭

# Algolia search
algolia_search:
  enable: true   # ← 确保 Algolia 搜索已启用

在 _config.yml 中检查：

algolia:
  applicationID: 'eeeeee'
  apiKey: 'xxx'  # ← 这里应该使用 Search-Only API Key（用于前端）
  indexName: 'hexo'

⚠️ 注意区分两种 API Key：

• 前端使用：Search-Only API Key（安全，只读）
• 上传使用：Admin API Key（危险，可写）

原因 2：浏览器缓存

解决方法：

按 Ctrl + F5 强制刷新浏览器

原因 3：Hexo 缓存未清理

解决方法：

hexo cl   # 清理缓存
hexo g    # 重新生成
hexo s    # 启动服务器

Q5：如何更新已有文章的索引？

场景：修改了文章内容，需要更新搜索索引

解决方法：

# 直接运行脚本即可，会自动覆盖旧索引
.\upload-algolia.ps1

hexo-algolia 插件会：

1. 读取所有文章（包括修改过的）
2. 删除旧索引
3. 上传新索引

Q6：可以在 Linux/Mac 上使用吗？

PowerShell 版本：仅限 Windows

跨平台方案：创建 Bash 脚本

Linux/Mac 脚本（upload-algolia.sh）：

#!/bin/bash

echo -e "\033[32m[INFO] Starting Algolia index upload...\033[0m"

# Set Admin API Key
export HEXO_ALGOLIA_INDEXING_KEY="xxxxxxxxxxxxxxxxxxxxx"

# Upload index
echo -e "\033[33m[INFO] Uploading articles to Algolia...\033[0m"
hexo algolia

if [ $? -eq 0 ]; then
    echo ""
    echo -e "\033[32m[SUCCESS] Upload completed!\033[0m"
    echo ""
    echo -e "\033[36mNext steps:\033[0m"
    echo "  1. Run: hexo cl"
    echo "  2. Run: hexo g"
    echo "  3. Run: hexo s"
    echo "  4. Test search function on your website"
else
    echo ""
    echo -e "\033[31m[ERROR] Upload failed!\033[0m"
    echo ""
    echo -e "\033[33mPlease check:\033[0m"
    echo "  1. Application ID is correct"
    echo "  2. Admin API Key is correct (must have write permission)"
    echo "  3. Index 'hexo' exists in Algolia dashboard"
    echo "  4. API Key has 'addObject', 'deleteObject', 'editSettings' permissions"
fi

使用方法：

# 添加执行权限
chmod +x upload-algolia.sh

# 执行脚本
./upload-algolia.sh

六、脚本优化建议

1. 添加参数支持

支持通过参数传入 API Key：

param(
    [string]$ApiKey = "xxxxxxxxxxxxxxxxxxxxx"
)

$env:HEXO_ALGOLIA_INDEXING_KEY = $ApiKey

使用方法：

.\upload-algolia.ps1 -ApiKey "your_api_key"

2. 添加日志记录

记录每次上传的时间和结果：

# 在脚本末尾添加
$logFile = "algolia-upload.log"
$timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
$logMessage = "[$timestamp] Upload status: $LASTEXITCODE"
Add-Content -Path $logFile -Value $logMessage

3. 集成到发布流程

创建一个 publish.ps1 脚本：

# 一键发布脚本
Write-Host "=== Hexo Blog Publishing ===" -ForegroundColor Cyan

# 1. 清理缓存
Write-Host "[1/5] Cleaning cache..." -ForegroundColor Yellow
hexo cl

# 2. 生成静态文件
Write-Host "[2/5] Generating static files..." -ForegroundColor Yellow
hexo g

# 3. 上传 Algolia 索引
Write-Host "[3/5] Uploading Algolia index..." -ForegroundColor Yellow
.\upload-algolia.ps1

# 4. 部署到服务器
Write-Host "[4/5] Deploying to server..." -ForegroundColor Yellow
hexo d

# 5. 完成
Write-Host "[5/5] Done!" -ForegroundColor Green

4. 添加索引统计

显示上传的文章数量：

# 执行上传并捕获输出
$output = hexo algolia 2>&1

# 提取文章数量
if ($output -match "(\d+) records to index") {
    $count = $matches[1]
    Write-Host "Uploaded $count articles" -ForegroundColor Cyan
}

七、安全建议

不要将 API Key 泄露到公开仓库

⚠️ 危险操作：将包含 API Key 的脚本推送到 GitHub

解决方案 1：使用环境变量

1. 将 API Key 存储在系统环境变量中
2. 脚本从环境变量读取

# 设置系统环境变量（只需设置一次）
[System.Environment]::SetEnvironmentVariable('ALGOLIA_ADMIN_KEY', 'your_key', 'User')

# 脚本中读取
$env:HEXO_ALGOLIA_INDEXING_KEY = [System.Environment]::GetEnvironmentVariable('ALGOLIA_ADMIN_KEY', 'User')

解决方案 2：使用 .gitignore

# .gitignore
upload-algolia.ps1
algolia-config.txt
*.log

解决方案 3：使用配置文件

创建 algolia-config.json（不推送到 Git）：

{
  "apiKey": "xxxxxxxxxxxxxxxxxxxxx",
  "applicationID": "eeeee",
  "indexName": "hexo"
}

脚本读取配置：

$config = Get-Content -Path "algolia-config.json" | ConvertFrom-Json
$env:HEXO_ALGOLIA_INDEXING_KEY = $config.apiKey

八、总结

脚本的核心价值

通过这个简单的 PowerShell 脚本，我们实现了：

✅ 自动化：一键上传，无需记忆复杂命令
✅ 可靠性：自动设置环境变量，避免人为错误
✅ 友好性：彩色输出和清晰的提示信息
✅ 可维护性：统一管理 API Key，便于更新

适用场景

这个脚本特别适合：

• 📝 频繁更新博客的作者
• 🔄 需要批量更新索引的情况
• 👥 团队协作时统一操作流程
• 🚀 CI/CD 自动化部署流程

扩展阅读

• Algolia 官方文档
• hexo-algolia 插件文档

---

希望这个脚本能帮助你更高效地管理 Hexo 博客的搜索功能！如果有任何问题或建议，欢迎在评论区讨论。

---