基于WSL-Ubuntu的Jekyll al-folio学术主页全流程配置教程

发表于 2025-08-19 分类于博客维护阅读次数：本文字数： 3.7k 阅读时长 ≈ 7 分钟

配这个环境简直是崩溃……适逢网上关于学术主页的搭建教程少之又少，谨以本人微薄的学识解答一二

本地环境部署配置

关于如何用al-folio的模板Use this templete、如何配置wsl-Ubuntu，网上教程已经比较详细了，在这里就不在赘述。只提醒一点：如果wsl配崩了，可以用unregister在cmd界面重置wsl。

直接本地安装ruby（推荐，博主用的Windows）

一开始本人也是跟着官方的INSTALL.md走docker路线，就因为梯子卡了版本不对等各种原因一直卡住……虽然前两天docker已经本地部署成功，但是今日在某鱼求教大佬采用本地部署后编译效率简直高了不是一个数量级……因此还是推荐走本地ruby部署，具体流程如下：

先进入学术主页的文件夹目录（用wsl要加/mnt/）：如本人的是cd /mnt/c/AcademicPage（其实就是把al-folio名字改成AcademicPage了）
安装前置库：

1 2	sudo apt update sudo apt install -y git curl libssl-dev libreadline-dev zlib1g-dev autoconf bison build-essential libyaml-dev libreadline-dev libncurses5-dev libffi-dev libgdbm-dev

安装 rbenv 和 ruby-build

1	curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-installer \| bash

配置Shell环境：将 rbenv 添加到你的 .bashrc 或 .zshrc 文件中，使其在终端启动时加载

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
# 如果你使用 Zsh，请将上面的 .bashrc 替换为 .zshrc

安装、设置并验证 Ruby：注意此处ruby版本要>=3.4.2，不然push到github的时候会报错

1
2
3

rbenv install 3.4.2
rbenv global 3.4.2
ruby -v

安装 Bundler

1	gem install bundler

安装项目依赖：注意此时要处于你的al-folio目录下

1	bundle install

如果你打算使用 .ipynb 文件来展示代码和图表，安装 Jupyter Notebook

1
2
3

sudo apt update
sudo apt install python3-pip
pip install jupyterlab notebook

如果你不用 Jupyter，只是想让网站先跑起来，那最简单的办法就是把那个示例的 .ipynb 文件删掉（本人博客已经有专门的个人主页了因此就不再打开）

1	rm assets/jupyter/blog.ipynb

启动本地服务器

1	bundle exec jekyll serve

采用docker（官方方案，但不推荐，需要有代理）

首先得把代理设置好：要开虚拟网卡/TUN模式全局接管网络

然后下Linux版的docker到WSL：尽量不用docker-Desktop，反正博主是没配出来

# 停止并移除所有可能存在的旧 Docker 包
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg; done

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker $USER

#验证上述docker安装是否成功
docker run hello-world
--示例输出：
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
...
Digest: sha256:...
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

事实证明只要网络好上述过程应该遇不到什么问题，博主卡了很久也是因为docker-Desktop一直配置不好……

这样完成过后就可以接着官方的走：

1 2	docker compose pull docker compose up

理论上这样完了就ok了

push推送上github操作雷点

虽然已经玩过hexo的个人主页也就是大家看到的这个网页，但是还是踩了坑。雷点就在于部署的时候进入个人主页仓库的Settings->Pages不能选Github Actions而是Deploy from a branch->gh-pages

利用脚本提升部署速度

像hexo提供了快捷的处理页面命令行如hexo g/hexo s/hexo d/hexo clean等，而al-folio是没有的，这样每次都得git…来执行内容就很麻烦，因此可以配置脚本来使用

nano ~/.bashrc
#在打开文件的末尾输入
alias g='git add . && git commit -m "Update content"'
alias s="docker compose up"
alias c="docker compose down && rm -rf _site .jekyll-cache"
alias d='git push origin main'
alias rs='bundle exec jekyll serve'
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Ctrl+X退出，卡在那提示输入yes/no就打一个y然后Enter就可以回到终端
source ~/.bashrc

source ~/.bashrc后更改就生效了，随后就可以用g代替重新生成页面，d就可以推送上去了。

在我的定义里g就是用docker编译，rg也就是ruby s就是走ruby编译，这个命令行的形式可以自行定义。

对代码文件的一定修改

首先就是_config.yml要把url变成自己的url，baseurl设置为“ ”这样才不会又定位到al-folio

其次.github/workflows/deploy.yml要把ruby-version改成3.4.2/3.4/3.5或以上的版本；其他还有地方没改的也得改一下

这样基本上部署就没问题了