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 面板盯住首屏请求。
