al-folio 操作汇总 | Quaner's Blog

更新al-folio版本

升级前准备

确认工作区状态
```
git status
```
升级前尽量保证工作区是干净的，避免 rebase 过程中把普通修改和升级冲突混在一起。
提交并推送当前代码
```
git checkout main
git add <需要保存的文件>
git commit -m "chore: save current site before upgrade"
git push
```
如果远端已经有当前代码，后续升级出问题时可以从远端恢复，不需要额外创建本地备份分支。
拉取上游并确认版本
```
git fetch upstream --tags
git tag
git log --oneline --decorate --max-count=10 upstream/main
```
后续命令中的 v0.16.3 只是示例版本，实际升级时替换成 git tag 中自己要升级到的版本。

rebase 升级流程

使用 rebase 进行升级，把自己的站点修改重新应用到新版 al-folio 之上。

rebase 到目标版本
```
git checkout main
git rebase v0.16.3
```
这里的 v0.16.3 需要替换成目标 tag，例如 v0.16.3、v0.17.0 等。

如果不指定 tag，而是直接升级到上游最新版本，可以使用：
```
git checkout main
git rebase upstream/main
```
查看冲突状态并处理

rebase 过程中如果出现冲突，先查看当前卡在哪些文件上：
```
git status
```
处理本次遇到的示例文章删除冲突

如果出现类似：
```
CONFLICT (modify/delete): _posts/2015-10-20-math.md deleted in <目标版本> and modified in HEAD.
```
如果这些是 al-folio 示例文章，不需要保留，可以接受删除：
```
git rm _posts/2015-10-20-math.md
```
如果是自己的文章，需要保留：
```
git add _posts/2015-10-20-math.md
```
处理本次遇到的 package.json 和 package-lock.json 冲突

处理思路是保留新版依赖结构，再确认自己的必要依赖没有丢失。

如果手动编辑冲突块，要删除所有冲突标记：
```
< < < < < < < HEAD
= = = = = = =
> > > > > > > commit-id
```
例如 package-lock.json 中 node_modules/@playwright/test 只应该描述 @playwright/test 自己，不应该把 prettier 塞进这个块里。prettier 只应该出现在文件开头根项目的 devDependencies 中。
检查冲突标记是否清理干净
```
git grep -n -E "^(<<<<<<<|=======|>>>>>>>)" -- .
```
如果还有输出，说明仍有冲突标记没有删干净。
标记冲突已解决并继续 rebase
```
git add <resolved-files>
git rebase --continue
```
注意这里不是 git commit。rebase 会继续应用后续提交。如果后续继续出现冲突，就重复执行：查看 git status、解决冲突、检查冲突标记、git add、git rebase --continue。

如果发现方向错了，可以回到升级前状态：
```
git rebase --abort
```
如果进入 nano 提交信息页面

git rebase --continue 后可能会打开 nano，让你确认当前提交信息。一般不需要修改，直接保存退出：
```
Ctrl + O
Enter
Ctrl + X
```
不要把提交信息清空，否则这一步提交会被中止。

异常排查记录

排查 socials 中 wechat-qr 报错

现象

启动时在渲染 about 页面报错：

Liquid Exception: undefined method `split` for nil

原因

_data/socials.yml 中的 wechat_qr 不是 jekyll-socials 识别的标准字段，会被当作自定义社交项，但值只是字符串（非 logo/title/url 结构），导致插件尝试解析 logo 时崩溃。

解决方案

直接注释 wechat_qr项，使其在search.liquid.js中走相关逻辑，防止``逻辑中出现异常
使用custom_social的方式来自定义WeChat社交项

custom_social 的 logo 必须是网络地址

custom_social 中的 logo 使用本地路径时会触发插件内部 relative_url 报错。建议使用完整的 https URL。

配置 CV 的正确方式

在 al-folio 0.16.3版本中，简历内容主要在 _data/cv.yml 中维护，_pages/cv.md 只是渲染入口。如果升级后 CV 显示异常，优先检查：

_data/cv.yml 是否符合新版结构
_pages/cv.md 是否引用了正确的 layout / 数据源