📝 笔记总结

1. with: 部分添加 requirements 参数；
2. 项目根目录创建 requirements.txt。

📖 内容来源

• Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
• 使用自定义GitHub Actions工作流将站点发布GitHub Pages中

⚠️ 错误提示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# .github/workflows/pelican.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [\"main\"]
  workflow_dispatch:
jobs:
  deploy:
    uses: \"getpelican/pelican/.github/workflows/github_pages.yml@main\"
    permissions:
      contents: \"read\"
      pages: \"write\"
      id-token: \"write\"
    with:
      settings: \"publishconf.py\"

使用官方的 pelican.yml，content 文件夹内有测试的文章 *.md，但是没有生成文章页面。

💡 错误原因

Could not import ‘markdown.Markdown’. Have you installed the ‘markdown’ package?
GitHub Actions 环境中没有安装 Markdown 支持，所以 Pelican 无法解析 .md 文件，导致处理了 0 篇文章。

✅ 解决方法

with: 部分添加 requirements 参数

• 指定需要安装的 Python 模块：

1
2
3

with:
  settings: \"publishconf.py\"
  requirements: \"pelican[markdown] typogrify markdown-include\"

• 或者指定一个requirements文件： -r requirements.txt：

1
2
3

with:
  settings: \"publishconf.py\"
  requirements: \"-r requirements.txt\"

• 完整的工作流文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

name: Deploy to GitHub Pages

on:
  push:
    branches: [\"main\"]
  workflow_dispatch:

jobs:
  deploy:
    uses: \"getpelican/pelican/.github/workflows/github_pages.yml@main\"
    permissions:
      contents: \"read\"
      pages: \"write\"
      id-token: \"write\"
    with:
      settings: \"publishconf.py\"
      requirements: \"-r requirements.txt\"

项目根目录创建 requirements.txt：

1
2

# 导出当前环境所有包
pip freeze > requirements.txt

典型的 Pelican 项目 requirements.txt 参考：

1
2
3
4
5
6
7
8
9
10

# Pelican 核心 + Markdown 支持
pelican[markdown]==4.12.0
# 排版优化（智能引号、连字符等）
typogrify==2.1.0
# 支持在 Markdown 中包含其他文件               
markdown-include==0.8.1
# 代码高亮
pygments==2.17.2
# 同时支持 Markdown 和 reStructuredText
# pelican[markdown,html_rst]

📝 笔记总结

1. 增加文件：svelte.config.js ；
2. 增加文件：src/routes/+layout.js 。

📖 内容来源

• SvelteKit 构建和部署 - 静态网站生成 - GitHub Pages
• SvelteKit Build and deploy - Static Site Generation - GitHub Pages

💡错误提示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: 'main'

jobs:
  build_site:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      # If you're using pnpm, add this step then change the commands and cache key below to use `pnpm`
      # - name: Install pnpm
      #   uses: pnpm/action-setup@v6
      #   with:
      #     version: 8

      - name: Install Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm i

      - name: build
        env:
          BASE_PATH: '/${{ github.event.repository.name }}'
        run: |
          npm run build

      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v5
        with:
          # this should match the `pages` option in your adapter-static options
          path: 'build/'

  deploy:
    needs: build_site
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

使用官方的 deploy.yml ，运行失败，下面提示：

错误表明 GitHub Actions 在运行 actions/upload-pages-artifact@v5 时，找不到 build/ 目录。

本地构建文件都生成在 .svelte-kit/output/server/ 目录下，而不是 build 文件夹，说明 adapter-static 可能没有正确执行，或者构建过程在预渲染阶段失败了。

🚀 官方方法

使用 npm i -D @sveltejs/adapter-static 安装，然后将适配器添加到你的 svelte.config.js 中。

1. 增加文件：svelte.config.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import adapter from '@sveltejs/adapter-static';

export default {
kit: {
adapter: adapter({
// default options are shown. On some platforms
// these options are set automatically — see below
pages: 'build',
assets: 'build',
fallback: undefined,
precompress: false,
strict: true
})
}
};

2. 增加文件：src/routes/+layout.js

1
2

// This can be false if you're using a fallback (i.e. SPA mode)
export const prerender = true;

💎 解决结果

文件生成在 .svelte-kit/output/server/ 和 build 文件夹。

📝 笔记总结

今天发现私有仓库的 Actions 运行失败了，下面提示：

The job was not started because recent account payments have failed or your spending limit needs to be increased. Please check the ‘Billing & plans’ section in your settings

我查询了一下，原来是免费额度用完了，顺便多了解了下。

查询：Settings → Billing and plans → Overview

页面中有一个 "Usage by products" 区域，点击 Actions 标签。

额度不够，是不是设置一个小号或者组织差不多够用。

📖 内容来源

• GitHub Actions 免费额度（DeepSeek）

GitHub Actions 的免费额度主要根据仓库是公开还是私有以及账户订阅计划来决定。核心原则是：公开仓库完全免费，私有仓库有每月额度限制。

把不同计划的免费额度表格查看：

提示：表格中的存储额度是工件（Artifacts） 和缓存（Cache） 共享的总和。缓存每个仓库还有额外的 10 GB 限制。

💡 超限后会发生什么？

• 如果设置了支出限额：一旦用完免费额度，超出的部分会按标准费率（Linux 约 $0.008/分钟）计费，直到设置的限额为止。
• 如果未设置支出限额（限额为 0）：私有仓库的 Actions 会停止运行，直到下一个计费周期重置。

🚀 一些关键细节和限制

• 工作流并发限制：GitHub Free 计划最多允许 20 个作业并发运行。如果超出，作业会进入排队状态。
• 单次作业超时：GitHub 托管运行器上的单个作业最多运行 6 小时，超时后会被自动取消。
• 存储扣费逻辑：存储费用是按小时计费并累积的。删除文件只能阻止未来继续计费，但无法免除文件在留存期间已经产生的费用。
• 账户计费独立：个人账户和组织的付费额度是分开的，为组织付款不会覆盖到个人账户。
• Copilot 代码评审：这项功能（如果启用）在私有仓库中也会消耗 Actions 分钟数。

💎 总结与建议

如果是开源项目或个人学习，公开仓库是零成本的最佳选择。如果必须使用私有仓库，建议密切关注仪表盘上的用量，并根据实际情况设置支出限额，防止意外超支。

📝 笔记总结

目前最好用的 Next.js 博客模板，首选功能最全的 tailwind-nextjs-starter-blog，它几乎涵盖了个人博客可能需要的所有功能，而且社区非常活跃。如果想找一个更轻量、更现代的选择，nextjs-mdx-blog-template 也很不错，基于最新的 Next.js 15 和 React 19

Next-js-Blog-Boilerplate

项目名称： ixartz/Next-js-Blog-Boilerplate
适用场景： 快速上手，希望项目结构清晰、易于维护的开发者。
核心特点：

• 简洁的 CLI 工具一键创建项目，快速启动开发。
• 整合了 Radix UI、Lucide 图标等现代 UI 库，界面组件丰富。
• 项目结构清晰规范，易于维护和二次开发。
• 内置 TypeScript 支持和 ESLint 配置，保证代码质量。
  项目演示： creativedesignsguru.com
  GitHub 地址： github.com/ixartz/Next-js-Blog-Boilerplate

next-mdx-blog

项目名称： leerob/next-mdx-blog
适用场景： Next.js 初学者，或希望从一个轻量、官方风格项目开始进行学习的开发者。
核心特点：

• 由 Vercel 的开发者关系负责人（Lee Robinson）维护，代码结构清晰规范。
• 基于 Next.js、MDX 和 Tailwind CSS 构建，轻量简洁。
• 可作为理解 Next.js + MDX 博客核心逻辑的绝佳起点，便于进行高度定制。
• 集成了 Vercel Analytics。
  项目演示： next-blog-mdx.vercel.app
  GitHub 地址： github.com/leerob/next-mdx-blog

🌟 nextjs-mdx-blog-template

项目名称： loke-dev/nextjs-mdx-blog-template
适用场景： 追求极致简洁、最新 Web API 和流畅动画体验的开发者。
核心特点：

• 采用 Next.js 15 的 App Router 和 React 19 Server Components。
• 内置 View Transitions API，实现平滑的页面过渡动画。
• 使用 shadcn/ui（Radix UI）保证可访问性，Shiki 实现代码高亮。
• 项目结构清晰，对 SEO 友好，开箱即用。
  项目演示： nextjs-mdx-blog-template.vercel.app
  备用演示： nextjs-mdx-blog.loke.dev
  GitHub 地址： github.com/loke-dev/nextjs-mdx-blog-template

nextjs-portfolio-blog-research

项目名称： zhengzangw/nextjs-portfolio-blog-research
适用场景： 追求现代化设计、国际化支持，以及希望尝试最新技术栈的研究者、开发者与创作者。
核心特点：

• 技术栈新，采用 Next.js 15、React 19 和 Tailwind CSS 4。
• UI 精美，使用 shadcn/ui 和 Framer Motion 构建组件与动画。
• 支持 AI 辅助定制（Cursor Rules）和中英双语国际化（i18n）。
• 内置丰富的作品集、博客模块，SEO 优化完善（JSON-LD、Open Graph），性能出色。
  项目演示： nextjs-portfolio-blog-research.vercel.app
  备用演示： www.zangwei.dev/open-source/nextjs-portfolio-blog-research/docs
  GitHub 地址： github.com/zhengzangw/nextjs-portfolio-blog-research

nextjs-sanity-blog

项目名称： @multidots/sanity-blog-theme
适用场景： 需要复杂内容结构（如有独立作者、分类、SEO管理）的团队或个人项目。
核心特点：

• 结合 Sanity CMS（强大的结构化内容平台），提供灵活的内容建模能力。
• 包含页面构建器和编辑器友好界面，方便非技术人员管理内容。
• 支持多作者、分类、标签、SEO 元数据管理等复杂内容结构。
• 基于 Next.js 和 Sanity 官方最佳实践构建。
  项目演示： www.sanity.io/templates/nextjs-blog
  GitHub 地址： github.com/multidots/nextjs-sanity-blog
  GitHub 备用： github.com/multidots/sanity-blog

🌟 NotionNext

项目名称： QiLOL/NotionNext
适用场景： 习惯使用 Notion 写作，希望将 Notion 作为 CMS（内容管理系统）快速搭建博客或知识库的用户。
核心特点：

• 基于 Next.js 和 Notion API，将 Notion 笔记渲染为静态博客页面。
• 内置多达 25 种主题，可一键切换。
• 支持多种评论系统（Twikoo, Giscus, Gitalk 等）。
• 项目活跃，持续更新，提供详细的中文文档。
  项目演示： preview.tangly1024.com
  GitHub 地址： github.com/QiLOL/NotionNext

starter-nextjs-blog

项目名称： Hashnode/starter-nextjs-blog
适用场景： 习惯在云端写稿、管理内容，又想自己搭建前端、保持UI高度自定义的创作者。
核心特点：

• 结合 Hashnode 强大的云端 CMS 管理后台，前端完全自定义。
• 通过 GraphQL API 获取内容，支持实时预览。
• 内置 SEO 优化，与 Hashnode 生态无缝集成。
• 适合已有 Hashnode 账号、希望保持写作习惯但拥有独立前端的用户。
  项目演示： github.com/Hashnode/starter-nextjs-blog
  GitHub 地址： github.com/Hashnode/starter-nextjs-blog

tailblaze

项目名称： tailblaze
适用场景： 目标是将博客部署到 Cloudflare Pages，或需要一个高性能静态站点的开发者。
核心特点：

• 功能齐全，PWA 就绪，支持离线访问能力。
• 强调性能和页面速度，经过 Lighthouse 优化。
• 支持静态导出 (SSG)，可无缝部署到 Cloudflare Pages、Netlify 等平台。
• 基于 Next.js、Tailwind CSS 和 TypeScript 构建。
  项目演示： tailblaze.pages.dev
  GitHub 地址： github.com/samrobbins/tailblaze

🌟 tailwind-nextjs-starter-blog

项目名称： timlrx/tailwind-nextjs-starter-blog
适用场景： 个人技术博客、作品集网站，以及希望从 Jekyll/Hugo 迁移到 Next.js 的用户。
核心特点：

• 功能非常全面，社区活跃（9.7k Star），可视为"功能最全的博客启动模板"。
• 基于 Next.js、TypeScript 和 Tailwind CSS 构建，使用 Contentlayer 管理内容逻辑。
• 集成多种分析、评论、邮件订阅方案（如 Pliny 插件），支持 SEO、RSS、数学公式（KaTeX）、搜索（Kbar/Algolia）等。
• 提供多种博客布局和列表布局，支持多作者和标签系统。
  项目演示： tailwind-nextjs-starter-blog.vercel.app
  项目演示： 项目 README 列出多个使用该模板的示例网站。
  GitHub 地址： github.com/timlrx/tailwind-nextjs-starter-blog