安装Jekyll SEO Tag时出现Liquid Exception: Can't convert Hash into String错误的原因排查

这个错误我之前帮朋友排查过好几次，大概率是这几个原因导致的，你可以挨个排查试试：

• 配置文件_config.yml里的参数格式错误
  Jekyll SEO Tag会读取全局配置里的title、description、author等字段生成SEO标签，如果这些字段被写成了哈希（键值对）而不是纯字符串，就会触发转换错误。比如：
  错误写法：

  title:
    site: "My Awesome Blog"
  

  正确写法：

  title: "My Awesome Blog"
  

  检查下_config.yml里所有和SEO相关的字段，确保它们是纯字符串，没有嵌套的哈希结构。

• 页面/文章的Front Matter参数格式不对
  如果你某篇文章或者页面的Front Matter里，把title、description这类SEO依赖的字段写成了哈希形式，比如：

  ---
  title:
    en: "Hello World"
  ---
  

  SEO Tag在读取时会把这个哈希当成字符串处理，直接报错。你可以先暂时注释掉几篇文章的Front Matter，或者把所有相关字段改成纯字符串，看看错误是否消失，定位出问题的页面。

• Jekyll和SEO Tag版本不兼容
  不同版本的Jekyll SEO Tag对参数的解析逻辑有差异，如果你的Jekyll版本偏旧，却安装了最新版的SEO Tag，或者反过来，就可能出现类型转换的问题。可以在Gemfile里指定一个和你Jekyll版本匹配的稳定版，比如：

  gem "jekyll-seo-tag", "~> 2.8.0"
  

  然后运行bundle update jekyll-seo-tag重新安装适配的版本。

• {% seo %}标签传递了错误参数
  如果你在使用{% seo %}时加了自定义参数，而且参数值是哈希结构，比如：

  {% seo title: { site: page.title } %}
  

  这种写法会直接触发错误，{% seo %}的参数值必须是纯字符串，不能嵌套哈希。检查下你的{% seo %}标签有没有额外的参数，有的话改成字符串形式。

• head.html里的其他代码干扰
  虽然错误提示指向default.html，但问题可能出在_includes/head.html里的其他Liquid代码。比如你在{% seo %}前后有其他标签，不小心把某个哈希变量当成字符串输出，或者出现了变量名冲突，导致SEO Tag读取到了错误类型的变量。可以先把head.html里除了{% seo %}之外的代码暂时注释掉，看看错误是否消失，逐步排查出干扰的代码。

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