Minima主题本地Jekyll构建报错：include标签语法无效

核心原因分析 #

你遇到的构建错误本质是Liquid include标签引用了无效的空文件名路径（错误提示里的social-icons/.svg），结合注释social_links后构建正常的现象，大概率是以下两种情况：

1. Minima主题版本自动升级
   虽然你锁定了Jekyll 4.3.1，但项目依赖的Minima主题可能未在Gemfile中锁定版本，导致本地构建时拉取了更新后的Minima版本。新版本主题模板对图标引用的语法校验更严格，当social_links中有不匹配的配置时，会生成空文件名的include路径，触发语法错误。

2. social_links配置存在异常
   检查_config.yml中的social_links项：

   • 是否有拼写错误的平台名称（比如把github写成gitHub，或新增了Minima未支持的平台）；
   • 是否存在空的平台配置项（比如只写了键但没有值）。
     这些情况会让主题模板尝试引用不存在的图标文件，最终生成social-icons/.svg这种无效路径。

具体解决步骤 #

1. 锁定Minima主题版本 #

如果之前构建正常，说明旧版本Minima可兼容你的配置。在Gemfile中添加Minima版本锁定：

gem "minima", "~> 2.5.1" # 替换为你之前成功构建时的Minima版本

然后执行：

bundle install

强制使用指定版本的主题，避免自动升级带来的兼容性问题。

2. 修复social_links配置 #

逐一核对_config.yml中的social_links，确保每个平台名称都是Minima官方支持的（比如github、twitter、linkedin、email等），且没有空配置项。示例：

social_links:
  github: faceyneck
  twitter: your_twitter_handle

如果有自定义平台，需确保对应的图标文件存在于assets/social-icons/目录下，文件名与平台名称一致（比如custom-platform.svg）。

3. 修复模板文件（可选） #

如果需要使用新版本Minima，可以修改assets/minima-social-ico.html中的逻辑，添加空值判断，避免生成无效的include路径：

{% if social_link.platform %}
  {% include social-icons/{{ social_link.platform }}.svg %}
{% endif %}

内容的提问来源于stack exchange，提问作者faceyneck