jekyll在windows上使用和调试

关注

原创最新推荐文章于 2026-07-14 09:50:05 发布 1.1k 阅读 AI 写同款· GEO 优化 ›

GitHub Pages 静态网站部署全指南：路径、baseurl 与 Jekyll 构建原理静态网站托管是前端开发者和开源作者的基础能力，其核心在于理解‘构建+分发’机制而非简单文件上传。GitHub Pages 并非传统服务器，而是基于 Git 版本控制、Jekyll 自动构建与全球 CDN 分发的闭环系统。掌握 baseurl 的真实语义（子路径前缀而非根目录）、资源路径必须通过 relative_url 过滤器动态生成，是解决 404 和样式丢失的关键。该方案特别适合技术文档、个人博客、项目官网等纯静态内容场景，兼顾零运维、强版本一致性与 GitHub 原生安全。本文聚焦真实部署中高频卡点，阅读详情

1. Windows 上调试

1.1. 解决中文文件名问题

1.1.1. 修改ruby 库 URI::escape

修改文件： ruby-2.1.7-x64-mingw32\lib\ruby\2.1.0\uri\common.rb
修改：在 escape 方法中添加 us.encode!(“utf-8”)

    def escape(str, unsafe = @regexp[:UNSAFE])
      unless unsafe.kind_of?(Regexp)
        # perhaps unsafe is String object
        unsafe = Regexp.new("[#{Regexp.quote(unsafe)}]", false)
      end
      str.gsub(unsafe) do
        us = $&
        tmp = ''
        ### ### fix chinese folder name becomes illegible in jekyll 2017-07-13
        us.encode!("utf-8")
        ### ###
        us.each_byte do |uc|
          tmp << sprintf('%%%02X', uc)
        end
        tmp
      end.force_encoding(Encoding::US_ASCII)
    end

1.1.2. webrick 中文支持

webrick\httpservlet\filehandler.rb 的 prevent_directory_traversal 函数中

  ### ### wi-start @ 2017-07-17 
  # delete below
  #path = req.path_info.dup.force_encoding(Encoding.find("filesystem"))
  # add this
  #      this cause illegible characters in path, files in chinese folder 404
  path = req.path_info.dup.force_encoding("utf-8").encode("gbk")
  ### ### @ 2017-07-17

1.2. Windows 上报错 “Missing dependency: RedCloth”

>bundle exec jekyll build
Configuration file: D:/documentation-theme-jekyll/_config.yml
            Source: D:/documentation-theme-jekyll
       Destination: D:/documentation-theme-jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
You are missing a library required for Textile. Please run:
  $ [sudo] gem install RedCloth
  Conversion error: Jekyll::Converters::Textile encountered an error while converting 'hello.textile':
                    Missing dependency: RedCloth
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    Missing dependency: RedCloth

1.2.1. 解决方法

> bundle list RedCloth
D:\ruby-2.1.7-x64-mingw32\lib\ruby\gems\2.1.0\gems\RedCloth-4.3.2\ext

> cd D:\ruby-2.1.7-x64-mingw32\lib\ruby\gems\2.1.0\gems\RedCloth-4.3.2\ext

> mkdir 2.1

> xcopy /E redcloth_scan\* 2.1\

1.3. build 时，报错： Invalid GBK character

jekyll 3.5.1 | Error:  Liquid error (line 77): Invalid GBK character "\xE2" on line 108

1.3.1. scssfiy 时出问题，utf-8 的 scss 文件被误认为 GBK

原因

sass 处理 “@import” 时读取文件，使用 File.read 是该方法默认使用 Windows 中文环境的 GBK 编码。

改不了内建的 File.read ，就只能改 Sass 了，例如：

\sass-3.5.1\lib\sass\importers\filesystem.rb
Sass::Importers::_find

module Sass
  module Importers
    class Filesystem
      def _find(dir, name, options)
        full_filename, syntax = Sass::Util.destructure(find_real_file(dir, name, options))
        return unless full_filename && File.readable?(full_filename)

        # TODO: this preserves historical behavior, but it's possible
        # :filename should be either normalized to the native format
        # or consistently URI-format.
        full_filename = full_filename.tr("\\", "/") if Sass::Util.windows?

        options[:syntax] = syntax
        options[:filename] = full_filename
        options[:importer] = self
        ### ### 
        # remove
        #Sass::Engine.new(File.read(full_filename), options)
        # add
        Sass::Engine.new(File.read(full_filename, :encoding => "utf-8"), options)
        ### ###
      end
    end
  end
end

1.3.2. 解决 link tag 参数出现中文文件名时，报错：incompatible character encodings

报错信息

format_error: incompatible character encodings: UTF-8 and GBK (Encoding::CompatibilityError)

解决方法
ruby-2.3.3-x64-mingw32\lib\ruby\gems\2.3.0\gems\jekyll-3.3.1\lib\jekyll\liquid_renderer.rb

def file(filename)
    # 解决 link tag 参数出现中文文件名时，报错：
    #   `format_error': incompatible character encodings: UTF-8 and GBK (Encoding::CompatibilityError)
    # 加入一句代码
    filename.encode!("utf-8")
      
    ...
end

1.4. drafts 草稿模式使用 liquid link tag 无法找到文件，导致无法运行

问题描述
drafts 草稿模式使用 liquid link tag 无法找到文件，这些文件放在 _posts 里面，无法在草稿模式找到。
解决方法
修改 link tag 的源码，只是警告提醒，而不中止编译。

ruby-2.3.3-x64-mingw32\lib\ruby\gems\2.3.0\gems\jekyll-3.3.1\lib\jekyll\tags\link.rb

  def render(context)
    site = context.registers[:site]

    site.each_site_file do |item|
      return item.url if item.relative_path == @relative_path
      # This takes care of the case for static files that have a leading /
      return item.url if item.relative_path == "/#{@relative_path}"
    end

    # 找不到文档，只提醒，不报错而导致build中止。
    # 使用 drafts 的时候可能无法找到link的文档
    # 删除这一句
    #raise ArgumentError, <<eos
    # 添加这句话
    Jekyll.logger.warn "WARNING:", <<eos
    
Could not find document '#{@relative_path}' in tag '#{self.class.tag_name}'.

Make sure the document exists and the path is correct.
eos
  end

2. 附录

2.1. 找到当前 webrick 代码目录

1
2
3

shell> irb
irb> require "webrick/httpservlet"
irb> WEBrick::HTTPServlet::FileHandler.instance_method(:set_filename).source_location

收录于

标签

#jekyll #windows #ruby

Git Hook 自动化部署 Jekyll 博客：零手动发布实践静态博客生成器（如 Jekyll）依赖 Ruby 运行时，通过 Git 触发构建流程是实现自动化部署的核心范式。其原理在于利用 Git 的 post-receive 钩子作为轻量级 CI，结合 rbenv 管理可复现的 Ruby 环境，在服务器端完成 jekyll build 并同步至 nginx 根目录。该方案规避了 GitHub Pages 的环境不可控与 CI 工具的过度复杂，以最小技术栈达成‘提交即上线’的确定性交付。适用于技术博客、团队文档等静态站点的生产部署场景，尤其解决内容创作者面临的发布延迟阅读详情