Angular部署GitHub Pages时非根路径访问及重定向遇404问题求助

问题原因 #

GitHub Pages是静态文件托管服务，当直接访问user.github.io/example-app/auth/login这类非根路径时，服务器会尝试查找对应物理路径下的文件，但Angular作为单页应用（SPA），所有路由都是前端路由，服务器上不存在auth/login对应的实体文件，因此返回404。

• PWA安装后直接访问非根路径时，依然会先请求GitHub Pages服务器，触发同样的404逻辑；
• Lighthouse测试时直接请求服务器路径，也会因找不到对应文件返回404。

解决方案 #

方案1：手动添加404.html文件（最简有效） #

利用GitHub Pages的404页面机制，让服务器返回Angular的入口文件，由前端路由接管：

1. 执行构建命令（替换为你的仓库名）：

   ng build --prod --base-href "/example-app/"
   

2. 进入构建输出目录dist/example-app，复制index.html并重命名为404.html；
3. 将dist/example-app下的所有文件部署到GitHub Pages。

方案2：用angular-cli-ghpages自动化部署 #

这个工具会自动处理SPA路由适配，无需手动操作：

1. 全局安装工具：

   npm install -g angular-cli-ghpages
   

2. 构建并一键部署（替换仓库名）：

   ng build --prod --base-href "/example-app/" && ngh --dir dist/example-app
   

方案3：配置GitHub Pages的Jekyll规则 #

如果你的GitHub Pages默认启用了Jekyll，可通过配置文件实现路由重定向：

1. 在项目根目录创建_config.yml文件，添加内容：

   permalink: pretty
   include: ['_redirects']
   

2. 同目录创建_redirects文件，内容为：

   /* /index.html 200
   

3. 构建项目后，将_config.yml、_redirects和dist目录文件一起部署到GitHub Pages，服务器会将所有路径重定向到index.html。

注意事项 #

• 构建时的--base-href参数必须和GitHub Pages的仓库路径完全一致（比如你的仓库是example-app，就写/example-app/）；
• 部署完成后，直接访问非根路径测试，确认Angular路由能正常渲染对应页面。

内容的提问来源于stack exchange，提问作者Manuel Pereira Maldonado