GitHub Pages与Vercel双部署避坑指南：publicPath配置决定成败

一、为什么你的双平台部署总是失败？

许多开发者都遇到过这样的困境：精心完成的项目在本地运行完美，却在使用GitHub Pages和Vercel双部署时遭遇连环翻车。当你在两个平台看到截然不同的报错提示——CSS加载失败、资源路径404、页面样式错乱，问题的根源往往指向同一个关键配置：publicPath（或base路径）。

1.1 典型问题场景再现

场景A：GitHub Pages正常访问，Vercel部署后main.css加载失败
场景B：Vercel运行完美，GitHub Pages却显示空白页面
控制台报错特征：Failed to load resource (404)

二、双平台路径差异的底层逻辑

2.1 GitHub Pages的特殊要求

GitHub Pages默认部署在https://<username>.github.io/<repo-name>/这样的二级路径下，这意味着：

必须设置publicPath: '/repo-name/'
所有静态资源路径需要自动添加项目名前缀

2.2 Vercel的部署特性

Vercel的每个部署都拥有独立域名（或根路径），因此：

必须使用publicPath: '/'
绝对路径写法会导致资源加载失败

三、终极解决方案：动态路径配置

3.1 Vue项目配置示例

// vue.config.js
module.exports = {
  publicPath: process.env.NODE_ENV === 'github' 
    ? '/your-repo-name/' 
    : '/'
}

3.2 React/Vite项目配置

// vite.config.ts
export default defineConfig({
  base: process.env.DEPLOY_ENV === 'github' 
    ? '/repo-name/' 
    : '/'
})

3.3 环境变量判断技巧

GitHub Actions部署时注入DEPLOY_ENV=github
Vercel部署保持默认环境变量
本地开发设置publicPath: '/'

四、自动化部署最佳实践

4.1 GitHub Actions双路部署配置

name: Deploy
on: [push]
jobs:
  github-pages:
    runs-on: ubuntu-latest
    steps:
      uses: actions/checkout@v3
      run: DEPLOY_ENV=github npm run build
      uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

  vercel-deploy:
    runs-on: ubuntu-latest
    steps:
      uses: actions/checkout@v3
      run: npm run build
      uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}

4.2 缓存问题终极解决方案

在构建命令中追加版本号：npm run build version=1.2.3
配置Cache-Control响应头：max-age=31536000, immutable
避免使用?v=random等破坏缓存策略的方案

五、常见问题排查清单

问题1：部署后页面空白 → 检查路由模式是否为history模式
问题2：图标加载失败 → 确保favicon.ico存放在public目录
问题3：API请求404 → 配置环境敏感的API基地址

通过精准的publicPath配置和自动化部署方案，开发者可以同时享受GitHub Pages的免费托管优势和Vercel的极速全球CDN。记住：路径配置是双平台部署的生命线，正确的配置方案能让你的项目在两种部署环境中无缝切换，真正实现「一次开发，处处部署」的理想状态。