Windows11下Jekyll LiveReload失效，修改文件无自动刷新求助

算力阿峰

2026-6-17

问题描述

我在Windows11、Ruby3.3.5环境下，基于academicpages/academicpages.github.io仓库开发Jekyll站点，想实现LiveReload自动刷新功能。执行bundle exec jekyll s --livereload或jekyll serve -l -o后，站点能正常构建，终端输出如下：

C:\Users\K\Documents\GitHub\B-M.github.io>bundle exec jekyll serve --open-url --livereload --livereload-port 35730
Configuration file: C:/Users/K/Documents/GitHub/B-M.github.io/_config.yml
            Source: C:/Users/K/Documents/GitHub/B-M.github.io
       Destination: C:/Users/K/Documents/GitHub/B-M.github.io/_site
 Incremental build: enabled
      Generating...
       Jekyll Feed: Generating feed for posts
                    done in 2.529 seconds.
  Please add the following to your Gemfile to avoid polling for changes:
    gem 'wdm', '>= 0.1.0' if Gem.win_platform?
 Auto-regeneration: enabled for 'C:/Users/K/Documents/GitHub/B-M.github.io'
LiveReload address: http://127.0.0.1:35730
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.
        LiveReload: Browser connected

访问http://127.0.0.1:4000/能正常查看站点，但修改文件后页面不会自动刷新；访问http://127.0.0.1:35730时，页面一直显示This port only serves livereload.js over HTTP.。需要解决本地修改后自动刷新的问题。

我的Gemfile内容：

source 'https://rubygems.org'

group :jekyll_plugins do
  gem 'jekyll'
  gem 'jekyll-feed'
  gem 'jekyll-sitemap'
  gem 'jemoji'
  gem 'webrick', '~> 1.8'
end

gem 'github-pages'
gem 'tzinfo-data'
gem "jekyll-sass-converter", "1.5.2"

_config.yml内容：

# Welcome to Jekyll!
#
# This config file is meant for settings that affect your entire site, values
# which you are expected to set up once and rarely need to edit after that.
# For technical reasons, this file is *NOT* reloaded automatically when you use
# `jekyll serve -l -H localhost`. If you change this file, please restart the 
# server process.
timezone: UTC
livereload: true



# Basic Site Settings
locale                   : "en-US"
title                    : "Bahi / Site Title"
title_separator          : "-"
name                     : &name "Your Name"
description              : &description "personal description"
url                      : https://academicpages.github.io # the base hostname & protocol for your site e.g. "https://mmistakes.github.io"
baseurl                  : "" # the subpath of your site, e.g. "/blog"
repository               : "academicpages/academicpages.github.io"

# Site Author - The following control what appear as part of the author content on the side bar.
#               If a field is blank the icon and link will not appear, otherwise it will be shown.
#               Additional customization can be done by editing /_includes/author-profile.html
author:
  # Biographic information
  avatar           : "profile.png"
  name             : "a"
  pronouns         : # example: "she/her"  
  bio              : "Short biography for the left-hand sidebar"
  location         : "Earth"
  employer         : "Red Brick University"
  uri              : # URL
  email            : "none@example.org" 

  # Academic websites
  arxiv            : # URL - Update with the correct link to your profile
  googlescholar    : "https://scholar.google.com/citations?user=PS_CX0AAAAAJ"
  impactstory      : # URL
  orcid            : "http://orcid.org/yourorcidurl"
  semantic         : # URL
  pubmed           : "https://www.ncbi.nlm.nih.gov/pubmed/?term=john+snow"
  researchgate     : # URL

  # Repositories and software development
  bitbucket        : # Username - Update with your username on the site
  codepen          : # Username
  dribbble         : # Username
  github           : "academicpages"
  kaggle           : # Username  
  stackoverflow    : # User number or user number and name (i.e., use "1" or "1/jeff-atwood")    

  # Social media
  bluesky          : "bsky.app" # Replace this with you Bluesky username
  facebook         : # Username
  flickr           : # Username
  foursquare       : # Username
  goodreads        : # Username
  google_plus      : # Username
  keybase          : # Username
  instagram        : # Username
  lastfm           : # Username
  linkedin         : # Username
  mastodon         : # URL
  medium           : # URL
  pinterest        : # Username
  soundcloud       : # Username
  steam            : # Username
  telegram         : # URL
  tumblr           : # Username
  twitter          : # Username for X / Twitter
  vine             : # Username
  weibo            : # Username
  wikipedia        : # Username
  xing             : # Username
  youtube          : # Username
  zhihu            : # Username

# Publication Category - The following the list of publication categories and their headings
publication_category:
  books:
    title: 'Books'
  manuscripts:
    title: 'Journal Articles'    
  conferences:
    title: 'Conference Papers'

# Site Settings
teaser                   :  # filename of teaser fallback teaser image placed in /images/, .e.g. "500x300.png"
breadcrumbs              : false # true, false (default)
words_per_minute         : 160
future                   : true
read_more                : "disabled" # if enabled, adds "Read more" links to excerpts
talkmap_link             : false #change to true to add link to talkmap on talks page
comments:
  provider               : # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "custom"
  disqus:
    shortname            :
  discourse:
    server               : # https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963 , e.g.: meta.discourse.org
  facebook:
    appid                :
    num_posts            : # 5 (default)
    colorscheme          : # "light" (default), "dark"
staticman:
  allowedFields          : ['name', 'email', 'url', 'message']
  branch                 : "gh-pages" # "master", "gh-pages"
  commitMessage          : "New comment."
  filename               : comment-{@timestamp}
  format                 : "yml"
  moderation             : true
  path                   : "_data/comments/{options.slug}"
  requiredFields         : ['name', 'email', 'message']
  transforms:
    email                : "md5"
  generatedFields:
    date:
      type               : "date"
      options:
        format           : "iso8601" # "iso8601" (default), "timestamp-seconds", "timestamp-milliseconds"
atom_feed:
  hide                   : false     # change to true to hide the RSS feed in the footer
  path                   : # blank (default) uses feed.xml


# SEO Related
google_site_verification :
bing_site_verification   :
alexa_site_verification  :
yandex_site_verification :


# Social Sharing
twitter:
  username               : &twitter
facebook:
  username               :
  app_id                 :
  publisher              :
og_image                 :  # Open Graph/Twitter default site image
# For specifying social profiles
# - https://developers.google.com/structured-data/customize/social-profiles
social:
  type                   : # Person or Organization (defaults to Person)
  name                   : # If the user or organization name differs from the site's name
  links: # An array of links to social media profiles


# Analytics
analytics:
  provider               :  "false" # false (default), "google", "google-universal", "google-analytics-4", "custom"
  google:
    tracking_id          :


# Reading Files
include:
  - .htaccess
  - _pages
  - files
exclude:
  - "*.sublime-project"
  - "*.sublime-workspace"
  - .asset-cache
  - .bundle
  - .github
  - .jekyll-assets-cache
  - .sass-cache
  - assets/js/_main.js
  - assets/js/plugins
  - assets/js/vendor
  - CHANGELOG
  - Capfile
  - config
  - Dockerfile
  - Gemfile
  - Gruntfile.js
  - gulpfile.js
  - LICENSE
  - local
  - log
  - node_modules
  - package.json*
  - Rakefile
  - README
  - tmp
  - vendor
keep_files:
  - .git
  - .svn
encoding: "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"


# Conversion
markdown: kramdown
highlighter: rouge
lsi: false
excerpt_separator: "\n\n"
incremental: false


# Markdown Processing
kramdown:
  input: GFM
  hard_wrap: false
  auto_ids: true
  footnote_nr: 1
  entity_output: as_char
  toc_levels: 1..6
  smart_quotes: lsquo,rsquo,ldquo,rdquo
  enable_coderay: false


# These settings control the types of collections used by the template
collections:
  teaching:
    output: true
    permalink: /:collection/:path/
  publications:
    output: true
    permalink: /:collection/:path/
  portfolio:
    output: true
    permalink: /:collection/:path/
  talks:
    output: true
    permalink: /:collection/:path/


# These settings control how pages and collections are included in the site
defaults:
  # _posts
  - scope:
      path: ""
      type: posts
    values:
      layout: single
      author_profile: true
      read_time: true
      comments: true
      share: true
      related: true
  # _pages
  - scope:
      path: ""
      type: pages
    values:
      layout: single
      author_profile: true
  # _teaching
  - scope:
      path: ""
      type: teaching
    values:
      layout: single
      author_profile: true
      share: true
      comments: true
  # _publications
  - scope:
      path: ""
      type: publications
    values:
      layout: single
      author_profile: true
      share: true
      comments: true
  # _portfolio
  - scope:
      path: ""
      type: portfolio
    values:
      layout: single
      author_profile: true
      share: true
      comment: true
  # _talks
  - scope:
      path: ""
      type: talks
    values:
      layout: talk
      author_profile: true
      share: true


# Sass/SCSS
sass:
  sass_dir: _sass
  style: compressed # http://sass-lang.com/documentation/file.SASS_REFERENCE.html#output_style


# Outputting
permalink: /:categories/:title/
# paginate: 5 # amount of posts to show
# paginate_path: /page:num/
timezone: Etc/UTC # http://en.wikipedia.org/wiki/List_of_tz_database_time_zones


# Plugins
plugins:
  - jekyll-feed
  - jekyll-gist
  - jekyll-paginate
  - jekyll-sitemap
  - jemoji

# Mimic GitHub Pages with --safe
whitelist:
  - jekyll-feed
  - jekyll-gist
  - jekyll-paginate
  - jekyll-sitemap
  - jemoji


# Archives
#  Type
#  - GitHub Pages compatible archive pages built with Liquid ~> type: liquid (default)
#  - Jekyll Archives plugin archive pages ~> type: jekyll-archives
#  Path (examples)
#  - Archive page should exist at path when using Liquid method or you can
#    expect broken links (especially with breadcrumbs enabled)
#  - <base_path>/tags/my-awesome-tag/index.html ~> path: /tags/
#  - <base_path/categories/my-awesome-category/index.html ~> path: /categories/
#  - <base_path/my-awesome-category/index.html ~> path: /
category_archive:
  type: liquid
  path: /categories/
tag_archive:
  type: liquid
  path: /tags/
# https://github.com/jekyll/jekyll-archives
# jekyll-archives:
#   enabled:
#     - categories
#     - tags
#   layouts:
#     category: archive-taxonomy
#     tag: archive-taxonomy
#   permalinks:
#     category: /categories/:name/
#     tag: /tags/:name/


# HTML Compression
# - http://jch.penibelst.de/
compress_html:
  clippings: all
  ignore:
    envs: development

解决方案

按以下步骤排查修复：

添加wdm依赖（解决Windows文件监听问题）
终端已经提示需要安装wdm，这是Windows下Jekyll监听文件变化必需的依赖。修改你的Gemfile，加入以下内容：

gem 'wdm', '>= 0.1.0' if Gem.win_platform?

可以直接放在gem 'tzinfo-data'那一行后面。然后执行命令安装：

bundle install

安装完成后重启Jekyll服务。

检查增量构建设置
你的_config.yml里incremental: false，开启增量构建能加快更新速度，可改成incremental: true，然后重启服务测试。
确认修改的文件未被排除
查看_config.yml里的exclude列表，如果你修改的文件在这个列表里（比如assets/js/_main.js），Jekyll不会监听它的变化。如果需要监听这类文件，把它从exclude里移除。
检查浏览器缓存和LiveReload脚本

按Ctrl+F5强制刷新浏览器，清除旧页面缓存后再测试修改。
打开浏览器控制台（F12），查看是否有livereload相关报错，比如脚本加载失败。如果有，关闭广告拦截类插件，避免拦截livereload.js。

重置LiveReload连接
关闭当前站点标签页，重新打开http://127.0.0.1:4000/，再测试文件修改后的刷新效果。
尝试使用默认LiveReload端口
去掉命令里的--livereload-port 35730，用默认端口启动服务，避免端口冲突或配置问题：

bundle exec jekyll serve --open-url --livereload

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

Windows11下Jekyll LiveReload失效，修改文件无自动刷新求助

问题描述 #

解决方案 #

问题描述

解决方案