Vite 项目部署平台适配实战：Vercel、Netlify、Cloudflare Pages 与自建方案

共同能力：接收构建产物、边缘分发、为每次提交生成独立地址
差异能力：回退语法、变量注入时机、缓存头粒度、边缘函数、回滚方式

追求零运维、要预览环境 → Vercel / Netlify / Cloudflare Pages
已有云厂商对象存储与 CDN → 对象存储加 CDN（成本最低）
有合规、内网或特殊缓存需求 → 自建 nginx（控制力最强）

{
  "buildCommand": "npm run build", "outputDirectory": "dist",
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

{ "headers": [
  { "source": "/assets/(.*)", "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }] },
  { "source": "/index.html", "headers": [{ "key": "Cache-Control", "value": "no-cache" }] } ] }

[build]
  command = "npm run build"
  publish = "dist"
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

/api/*  https://api.example.com/:splat  200
/*      /index.html                     200

# public/_headers（放在 public/ 下，构建时原样拷进 dist）
/assets/*   → Cache-Control: public, max-age=31536000, immutable
/index.html → Cache-Control: no-cache

构建设置：
  Framework preset  → Vite
  Build command     → npm run build
  Build output      → dist

# public/_headers
/assets/*  → Cache-Control: public, max-age=31536000, immutable
# public/_redirects
/*  /index.html  200

# 1. 先同步带 hash 的静态资源（可长缓存、可并发）
aws s3 sync dist/assets s3://my-bucket/assets \
  --cache-control "public, max-age=31536000, immutable"
# 2. 再同步 HTML（短缓存）
aws s3 sync dist s3://my-bucket --exclude "assets/*" \
  --cache-control "no-cache" --delete

带 hash 的资源 → immutable；HTML 与 sw.js → no-cache；上传脚本必须按类型区分 Cache-Control，无法像 nginx 那样改配置即刻生效

回源规则：源站 403 / 404 → 回退 /index.html 并把状态码改为 200
例外：路径以 /assets/ 开头 → 绝不回退，否则脚本 404 返回 HTML 会触发 MIME 报错

server {
    listen 80;
    root /var/www/app/dist;
    location / { try_files $uri $uri/ /index.html; }          # SPA 回退
    location /assets/ {                                        # 带 hash，长缓存
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
    location = /index.html { add_header Cache-Control "no-cache"; }
}

index-a1b2c3.js       → 内容变则名变 → immutable 安全
index.html            → 名字恒定 → 必须 no-cache，否则永远拿不到新版本
sw.js / manifest.json → 名字恒定 → 必须 no-cache

gzip on;  gzip_min_length 1024;
gzip_types text/css application/javascript application/json image/svg+xml;
add_header X-Content-Type-Options nosniff;    # 配合 SPA 回退兜底 MIME 嗅探
add_header X-Frame-Options SAMEORIGIN;
add_header Referrer-Policy strict-origin-when-cross-origin;

用户访问 /dashboard/settings → 服务器无此文件
  → 回退返回 index.html（状态码 200）→ 前端路由解析路径并渲染

/app/*    /app/index.html   200
/blog/*   /blog/index.html  200
/*        /404.html         404

// 构建产物里已无 process.env，只有被替换后的字符串
const api = import.meta.env.VITE_API_BASE

<!-- public/config.js，部署后可直接替换，无需重新构建 -->
<script>window.__APP_CONFIG__ = { apiBase: '/api' }</script>

const cfg = (window as any).__APP_CONFIG__ ?? { apiBase: import.meta.env.VITE_API_BASE }

main 分支    → 生产域名
feature 分支 → https://feature-xxx.preview.example.com
PR 创建时    → 自动构建 + 评论区贴出预览链接（评审即可点开真实产物）

方案一：新版本先部署到 /v2/ 子路径，用 CDN 规则把 5% 流量导向它
方案二：用边缘函数按 Cookie 或请求头分流；方案三：先在小流量域名验证再切主域名

vercel promote <previous-deployment-url>   # Vercel：提升上一次部署
# Netlify：面板选历史部署点 Publish；对象存储：切回上一版本目录前缀

grep -o '/assets/[^"]*' dist/index.html          # HTML 引用的 hash 文件
ls dist/assets/*.map 2>/dev/null && echo "警告：sourcemap 未清理"
ls dist/_redirects dist/_headers dist/robots.txt; du -sh dist   # 约定文件与总体积

□ 输出目录为 dist，SPA 回退规则为「重写」语义
□ HTML 与 sw.js 缓存头为 no-cache，带 hash 资源为 immutable
□ VITE_ 变量已在目标环境配置并重新构建
□ 预览环境可访问，且后端接口白名单已放开
□ sourcemap 未进入生产产物（或已限制访问）
□ 历史产物已保留，回滚路径已验证