文章

快速上手

这份完整概述带你了解 Chirpy 的基础。 你将学习如何安装、配置、搭建第一个基于 Chirpy 的网站，并部署到 Web 服务器。

发表于
作者
7 分钟阅读
快速上手

创建站点仓库

创建站点仓库时，可以根据自身需求二选一：

方案 1：使用模板仓库（推荐）

该方式便于主题升级、隔离无关文件，适合只想专注写作、尽量少做配置的用户。

  1. 登录 GitHub，打开[模板仓库][starter]。

  2. 点击 Use this template（使用此模板）按钮，选择 Create a new repository（创建新仓库）。

  3. 将新仓库命名为 <username>.github.io，把 username 替换为全小写的 GitHub 用户名。

方案 2：Fork（复刻）主题仓库

该方式适合深度修改功能或界面，但后续升级主题比较麻烦。除非熟悉 Jekyll、打算大规模改动主题，否则不建议选择。

  1. 登录 GitHub。

  2. Fork 该主题仓库。

  3. 将新仓库命名为 <username>.github.io，把 username 替换为全小写的 GitHub 用户名。

配置开发环境

仓库创建完成后，接下来配置本地开发环境，主要有两种方式：

使用 Dev Containers（Windows 用户推荐）

Dev Containers 基于 Docker 提供隔离运行环境，避免和本机系统产生依赖冲突，所有依赖都在容器内部管理。

操作步骤：

  1. 安装 Docker：

    • Windows /macOS：安装 [Docker Desktop][docker-desktop]

    • Linux：安装 [Docker Engine][docker-engine]

  2. 安装 [VS Code][vscode]，再安装 [Dev Containers 扩展][dev-containers]。

  3. 克隆你的仓库：

    • Docker Desktop：打开 VS Code，[在容器卷中克隆仓库][dc-clone-in-vol]。

    • Docker Engine：先把仓库克隆到本地，再通过 VS Code [在容器中打开项目][dc-open-in-container]。

  4. 等待 Dev Containers 完成环境初始化。

本机原生环境（类 Unix 系统推荐）

类 Unix 系统可直接在本机搭建环境，性能最优；当然也可以选择 Dev Containers。

操作步骤：

  1. 参考 Jekyll 官方文档 https://jekyllrb.com/docs/installation/ 安装 Jekyll，同时确保已安装 [Git](https://xn–gitscm-kg0c.com/)。

  2. 将仓库克隆到本地。

  3. 如果是 Fork 的主题仓库，需要安装 [Node.js][nodejs]，在项目根目录执行脚本：bash tools/init.sh 完成仓库初始化。

  4. 在项目根目录运行命令 bundle install，安装全部依赖。

使用方法

启动 Jekyll 本地服务

在本地预览网站，执行下面命令：

1

$ bundle exec jekyll serve

如果你使用 Dev Containers，必须在 VS Code 的内置终端执行以上命令。

稍等几秒后，本地预览地址：http://127.0.0.1:4000。

基础配置

按需修改 _config.yml 中的配置项，常用参数：

  • url 站点访问域名

  • avatar 头像

  • timezone 时区

  • lang 语言

社交联系方式

侧边栏底部会展示社交账号，可在 _data/contact.yml 文件开启 / 关闭对应的联系方式。

自定义样式表

想要自定义样式：把主题文件 assets/css/jekyll‑theme‑chirpy.scss 复制到你站点的相同路径，在文件末尾追加自定义样式代码即可。

静态资源自定义

静态资源配置从 5.1.0 版本开始支持。静态资源 CDN 配置位于 _data/origin/cors.yml。可以根据网站发布地区的网络状况替换部分资源地址。

如果你希望全部静态资源自托管，请参考仓库文档：chirpy‑static‑assets。

部署

部署前，请检查 _config.yml，确认 url 配置正确。

如果你使用项目站点模式（非用户主页仓库），不配置自定义域名，或是要在 GitHub Pages 以外的 Web 服务器部署，务必设置 baseurl，值为项目名，开头带斜杠，例如 /project‑name。

下面二选一完成部署：

通过 GitHub Actions 部署

准备工作：

  • GitHub 免费版：仓库必须设为公开。

  • 如果仓库已经提交了 Gemfile.lock，且本机不是 Linux 系统，需要更新锁文件的平台列表：

    1

    $ bundle lock --add-platform x86_64-linux

接下来配置 Pages 服务：

  1. 进入 GitHub 仓库页面，打开 Settings（设置）→ 左侧 Pages。在 Build and deployment（构建和部署） 的 Source（源）下拉菜单选择 [GitHub Actions][pages-workflow-src]。

  2. 向 GitHub 推送代码，就会自动触发 Actions 工作流。进入仓库 Actions 标签页，可以看到 Build and Deploy 任务正在运行。构建成功完成后，网站就自动部署完毕。

访问 GitHub 给出的网址，即可打开你的网站。

本地手动构建部署（用于自建服务器）

自建服务器场景，需要在本地构建站点，再把构建产物上传服务器。

进入项目根目录，执行构建命令：

1

$ JEKYLL_ENV=production bundle exec jekyll b

除非手动指定输出路径，构建后的全部网站文件输出在项目根目录的 _site 文件夹，将该文件夹内全部内容上传到目标服务器即可。

补充小提示：

  • 新手强烈建议选 Option1 使用 chirpy‑starter 模板，不要 fork 主仓库，后续升级主题极其省心。

  • Windows 不想装 Ruby 环境，直接走 Dev Containers，开箱即用。

  • 写文档放 _tabs/，博客文章放 _posts/。

（注：部分内容由豆包工作 AI 生成）

博客, 教程
快速上手
本文由作者按照 CC BY 4.0 进行授权

热门标签

快速上手