在GitHub Pages部署静态项目报错，安装Sass后出现异常

我已将项目部署到GitHub Pages，但打开链接时显示错误页面（错误页面截图：）。项目访问地址：https://meriemu.github.io/map-mapbox-js/，GitHub仓库地址：https://github.com/Meriemu/map-mapbox-js。

在使用npm安装Sass之前并未出现此问题，不清楚问题出在哪里。项目仓库结构截图：。

我的package.json配置如下：

{
  "homepage": "https://Meriemu.github.io/map-mapbox-js",
  "name": "map-mapbox",
  "scripts": {
    "deploy": "gh-pages -d build",
    "sass": "sass scss:public",
    "sass:dev": "sass --watch --embed-source-map scss:public/styles",
    "sass:prod": "sass --no-source-map --style compressed scss:public/styles"
  },
  "dependencies": {
    "gh-pages": "^4.0.0"
  },
  "version": "1.0.0",
  ...
}

排查建议 #

• 检查部署目录的正确性
  你的deploy脚本指定部署build目录，但从仓库结构看，Sass编译产物在public/styles下。如果build目录为空或没有包含所有需要部署的文件（比如index.html、样式、JS等），部署后自然会报错。可以修改deploy脚本的目标目录为public，或者先把所有静态资源整理到build目录后再执行部署。

• 确认资源引用路径是否适配子路径
  项目部署在GitHub Pages的子路径/map-mapbox-js/下，HTML中引用样式、JS等资源必须使用相对路径（比如./styles/main.css），不能用绝对路径（/styles/main.css），否则浏览器会去根域名查找资源，导致404。另外，你的Sass脚本有两个不同的输出路径（public根目录和public/styles），容易造成路径混乱，建议统一编译到public/styles，并确保HTML中的引用路径和实际文件位置匹配。

• 查看gh-pages分支的实际内容
  直接访问仓库的gh-pages分支，检查部署上去的文件是否完整（尤其是index.html是否存在）。如果分支内容缺失，说明部署命令没有正确上传目标目录的文件，需要核对deploy脚本的参数是否正确。

• 确认部署前执行了完整的构建步骤
  package.json中没有定义build命令，部署前需要手动执行sass:prod编译生产环境样式，并确保所有需要部署的静态文件都已准备就绪。如果跳过构建直接执行npm run deploy，部署的就是空目录或不完整的内容，必然会出现错误页面。

• 统一homepage配置的大小写
  你的homepage配置中用户名为Meriemu，但实际访问地址是小写的meriemu。虽然GitHub Pages不区分大小写，但统一配置和访问地址的大小写可以避免潜在的路径匹配问题。

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