如何通过VSCode部署静态网站到GitHub Pages？【教程】

vscode不直接部署网站，真正部署由gitHub Actions完成；github Pages仅托管静态文件，需明确指定源（gh-pages分支或main分支的docs/目录），并正确配置base路径以避免404。

VSCode 本身不直接部署网站，它只是编辑器；真正完成部署的是 GitHub Actions 自动化流程，VSCode 只负责写代码、提交到仓库。别在 VSCode 里找“一键部署”按钮——那不存在。

GitHub Pages 部署必须用 gh-pages 分支或 main 分支的 docs/ 目录

GitHub Pages 不会自动构建你的源码，它只托管静态文件。你得明确告诉它：「我要把哪一堆 html/css/js 文件当作网站根目录」。

• 用户站点（username.github.io）：只能用 main（或 master）分支的根目录
• 项目站点（username.github.io/repo-name）：可用 gh-pages 分支，也可用 main 分支的 docs/ 目录
• 如果选 gh-pages 分支，记得在 GitHub 仓库 Settings → Pages → Source 里手动切换分支，否则页面不会生效

用 GitHub Actions 自动构建并推送到 gh-pages 分支

手动构建 + 手动推送容易出错，且无法处理如 npm run build 生成的 dist/ 目录。推荐用 .github/workflows/deploy.yml 自动化：

name: Deploy to GitHub Pages on:   push:     branches: [main]     paths: ['src/**', 'public/**', 'vite.config.js', 'package.json'] jobs:   deploy:     runs-on: ubuntu-latest     steps:       - uses: actions/checkout@v4       - uses: pnpm/action-setup@v4       - run: pnpm install       - run: pnpm run build       - uses: peaceiris/actions-gh-pages@v3         with:           github_token: ${{ secrets.GITHUB_TOKEN }}           publish_dir: ./dist

• paths 过滤触发条件，避免每次改 README 都触发构建
• peaceiris/actions-gh-pages 会自动创建并推送 gh-pages 分支，无需本地配置 Git remote
• 确保 publish_dir 指向你实际构建输出的目录（Vite 是 dist/，Create react app 是 build/）

本地预览和路径问题最容易导致 404

GitHub Pages 的项目站点默认挂载在子路径（如 /my-app/），但本地 index.html 直接双击打开时，所有相对路径（./assets/logo.png）会按文件系统解析，不是按 URL 路径。结果就是：本地能看，上线全白屏或报 404。

• Vite 项目必须在 vite.config.js 中设置 base: '/repo-name/'（结尾带斜杠）
• React router 用户需用
• 检查浏览器开发者工具 Network 标签页，看哪些资源返回 404 —— 通常就是 base 或 basename 没配对
• 不要依赖 file:// 协议测试，用 npx serve -s dist 或 VSCode 插件 Live Server 启一个本地服务再测

真正卡住人的往往不是部署动作本身，而是构建产物路径、GitHub Pages 的 base URL 规则、以及 Actions 权限与缓存之间的微妙冲突。建议第一次部署后，立刻去仓库 Settings → Pages 页面确认地址是否显示 “Your site is published at …”，再打开那个链接，用 Network 面板盯住首屏请求。