当你使用 Eleventy（11ty）构建静态站点并自动部署到 GitHub Pages 时，尽管大部分流程可以顺利完成，但仍有不少开发者会遇到一些共性问题。这些问题往往导致站点链接失效、路径错误、样式或资源加载不正确、部署失败等现象。下面是几个常见问题与解决方法，希望能帮你快速定位和修复。
常见问题与对应解决方案
问题 1：链接、资源文件路径错误（路径带 repo 名或不带 repo 名）
症状：部署后访问站点时，资源（CSS / JS /图片）加载 404，导航链接指向错误，比如指向 /about/ 而不是 /<repo-name>/about/，或者反过来带有 repo 名但你期望不带。
原因：Eleventy 在生成时默认假设站点部署在根路径 /。当实际上是部署在子路径（即 Project site，如 https://youruser.github.io/your-repo/）时，需要配置 pathPrefix，并让生成的链接和资源引用带上这个前缀。
解决方案：
1. 在你的 Eleventy 配置文件（如 .eleventy.js 或 .eleventy.config.js）中设置 pathPrefix，例如：
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(require("@11ty/eleventy").EleventyHtmlBasePlugin);
return {
pathPrefix: "/your-repo-name/",
// 其它配置项，例如 dir.input, dir.output 等
};
};
2. 使用 EleventyHtmlBasePlugin 插件，这样 Eleventy 会在生成的 HTML 中加入 <base href="...">，使所有相对资源引用和链接都会自动加前缀。
3. 如果你用过自定义脚本生成图片 /处理资源（例如处理 srcset、图片压缩、bundle 等），要确认这些脚本也“知道”这个前缀（即在生成资源路径时考虑 pathPrefix）。
问题 2：GitHub 自动触发 Jekyll 构建冲突或语法错误
症状：GitHub Pages 在部署时报错，说 Jekyll 语法错误或尝试解释某些 Liquid include 标签，或者报错 “Invalid syntax” 等，导致站点不能正确生成或样式、布局出问题。
原因：GitHub Pages 默认启用了 Jekyll，当它在部署静态站点时，如果没有明确禁止 Jekyll，它会把某些文件按 Jekyll 处理。如果你的站点又包含以 .liquid 或 .html 带 Liquid 模板语法的内容，冲突就会出现。
解决方案：
在你的项目根目录下添加一个空文件 .nojekyll，以告诉 GitHub Pages 不使用 Jekyll 构建。这样它不会把你的文件按 Jekyll 的规则去处理。
确保 .nojekyll 被通过 Eleventy 的 passthrough 或手动放到输出目录（publish 目录）里。如果你用 GitHub Actions 构建并部署，要确保在构建输出的 _site 或 docs 文件夹里包含 .nojekyll。
问题 3：输出目录或分支设置错误导致内容没部署或被覆盖
症状：在 GitHub Pages 设置里选错分支或文件夹；或者你在 Actions workflow 里 publish 的目录与 Pages 设置里源目录不匹配；结果部署看起来成功，但页面内容不更新或为空白。
原因：GitHub Pages 支持从几个不同的地方发布内容，比如 gh-pages 分支、main 的 docs 文件夹、或者自定义分支／文件夹。Eleventy 构建输出目录（例如 _site 或 docs 或者例如 public）必须与 Pages 设置里的“源（Source）”配置一致。
解决方案：
1. 确认在 GitHub 仓库设置 → Pages（或“Pages、GitHub Pages”部分）中 Source（源）选项与你构建输出对应。例如，如果你使用 gh-pages 分支，那就将 Source 设置为 gh-pages；如果构建输出在 main 分支的 docs 文件夹，则设置为 main + docs。
2. 在你的 workflow 或构建脚本里，清晰指定 Eleventy 的输出目录，且 publish 到正确位置。例如把输出目录设为 docs 或 gh-pages 分支的根目录。
3. 在 package.json 或 workflow 中的脚本里统一标明路径。例如：
"scripts": {
"build": "eleventy",
"build:gh-pages": "eleventy --output docs"
}
Workflow 中用 publish_dir: docs 或 publish_dir: _site 与 Pages 的源目录对应。
问题 4：GitHub Actions Workflow 权限／自动部署出错
症状：提交推送后 GitHub Actions 没有执行、输出失败、部署任务报权限错误或 publish 无效。
原因：
- Actions 权限设置不当（例如没有 write 权限或 Pages 写权限）。
- 使用的 Action（deploy action）没有正确配置 github_token 或 secrets。
- workflow 文件 YML 格式、路径不对。
- 在使用新的 GitHub Pages “部署来源”选项或 “Actions / deploy-pages@v2” 等新的 action 时没有配置相应权限。
解决方案：
1. 在仓库 Settings → Actions 或者 Settings → Pages 确认你允许使用 GitHub Actions 部署 Pages，并授予必要权限（读 / 写 contents、写 pages、id-token 等）。
2. workflow 文件中确保使用正确的 action，例如 actions/deploy-pages@vX 或 peaceiris/actions-gh-pages@vX，并正确传递 publish_dir、cname 等参数。
3. 使用 checkout、setup-node 等步骤，以便你能在 workflow 中拉取代码、安装依赖、构建静态站点。
4. 若你使用 Projects site 或 subdir 部署，确保 workflow 步骤中 build 的脚本中也考虑 pathPrefix。
问题 5：自定义域名 (Custom Domain) 或 CNAME 文件问题
症状：你设定了自定义域名后，一推新内容，自定义域名不生效；或者 GitHub Pages 的 CNAME 文件被覆盖、丢失；站点跳转错到 GitHub 的默认域名。
原因：部署过程中输出目录里没有 CNAME 文件被 passthrough；或者部署 action 覆盖了先前的 CNAME；或者 Pages 设置中自定义域名没被正确保存。
解决方案：
在项目根目录添加名为 CNAME 的文件，内容是你的自定义域名（例如 www.mydomain.com），不要扩展名或额外换行空格。
在 Eleventy 的配置中，把这个文件作为静态资源复制到输出目录（passthrough copy），例如：
eleventyConfig.addPassthroughCopy("CNAME");在 GitHub Actions /部署流程中，确保 publish 操作不会清除掉这个文件，或者每次部署后也包括 CNAME 文件。
在仓库设置里的 Pages → Custom domain 填写你的域名，并开启相关的 enforced HTTPS（如果你需要）。
问题 6：样式、CSS 或前端资源在部署后显示不对或丢失
症状：部署后页面基本结构没问题，但 CSS 样式丢失，图片或字体加载失败，或者页面显示未格式化（未加载样式）。
原因：
- 链接引用静态资源路径写死，未考虑 pathPrefix 或自定义目录。
- 构建过程中静态文件（CSS、图片、字体）未被 passthrough copy。
- 样式文件／资源所在的目录未被包含在输出目录／workflow publish 目录。
- 有些资源路径是绝对路径（起始 /static/... 或 /css/...），在 GitHub Pages 的子目录环境中会指向根而非子目录。
解决方案：
1. 在 Eleventy 配置中使用 addPassthroughCopy 方法，把静态资源文件夹（如 css、assets、images 等）复制到输出目录。
eleventyConfig.addPassthroughCopy("src/css");
eleventyConfig.addPassthroughCopy("src/images");2. 链接静态资源时尽量使用相对路径或依赖 pathPrefix 加前缀。使用内置的滤镜或变量生成链接，比如 {{ '/css/styles.css' | url }} 或其他能结合 pathPrefix 的方式。
3. 检查 build 的输出目录 _site（或 docs 或自定义）是否包含所有静态文件；在本地 build 后先在静态服务器上测试是否所有样式／资源加载正常，再推送部署。
总结与最佳实践提示
- 在开始部署前，一定先在本地 build 并用本地静态服务器测试所有页面及资源链接是否正确，包括在子路径／带前缀情况下。
- 使用版本控制管理所有配置文件（.eleventy.js、workflow，package.json 等），不要在部署过程中手动修改忽略或遗漏关键文件如 .nojekyll 或 CNAME。
- 在 workflow 或 CI/CD 脚本里保持清晰与一致性：输出目录、分支、GitHub Pages 设置要对应上。
- 若项目以后可能会移动域名或 repo 名变动，尽量把路径前缀配置集中在一个地方（配置文件／环境变量），并不要在模板中硬编码很多绝对路径。
Eleventy + GitHub Pages 的组合非常强大且适合个人博客或小型文档类站点，虽然部署过程有不少坑，但只要理解上述常见问题与解决方案，多数问题都能被迅速解决。