VitePress部署时如何配置自定义域名？

Question

在使用 VitePress 部署静态站点时，如何正确配置自定义域名以确保通过 HTTPS 正常访问？常见问题包括：部署到 GitHub Pages 或 Netlify 后，虽然默认域名可访问，但绑定自定义域名时出现解析失效、HTTPS 证书未生效或资源路径加载错误（如 CSS/JS 404）。需确认 DNS 解析设置正确，同时在 VitePress 的 `config.js` 中合理配置 `base` 路径，并在部署平台添加自定义域名后等待 SSL 证书自动签发。如何解决这些配置冲突？

Answer 1

一、VitePress 静态站点部署中自定义域名与 HTTPS 配置全解析

1. 基础概念：理解 VitePress 的部署机制与静态资源路径

VitePress 是基于 Vite 构建的静态站点生成器，适用于文档类网站。其输出为纯静态文件（HTML、CSS、JS），可通过 GitHub Pages、Netlify、Vercel 等平台部署。

关键配置项位于 vitepress/config.js 中的 base 字段，用于指定站点根路径：

export default {
  base: '/your-repo/', // GitHub Pages 子路径
  // base: '/',        // 自定义域名根路径
}

若未正确设置 base，在非根路径下访问时，资源请求路径会出错，导致 CSS/JS 404。

2. DNS 解析配置：确保域名指向正确的托管服务

将自定义域名绑定到部署平台需修改 DNS 记录。常见配置如下表所示：

域名类型	记录类型	主机名	目标值	适用平台
裸域（example.com）	A 或 ALIAS/ANAME	@	GitHub Pages IP 或 Netlify 提供的别名	GitHub / Netlify
子域（docs.example.com）	CNAME	docs	your-site.netlify.app	Netlify

DNS 更改后需等待 TTL 过期，通常需数分钟至 48 小时。

3. 平台侧域名绑定：在 GitHub Pages 与 Netlify 中添加自定义域名

1. GitHub Pages：进入仓库 Settings → Pages → Custom domain，输入域名（如 example.com）并保存。
2. Netlify：在站点 Dashboard → Domain Settings → Add custom domain，输入域名并确认。
3. 平台将自动触发 Let's Encrypt 证书签发流程，状态显示为 "SSL/TLS certificate is being issued"。
4. 证书签发成功后，强制启用 HTTPS（Netlify 默认开启）。

注意：首次绑定后需等待 5-30 分钟，期间可能提示“证书未就绪”。

4. HTTPS 证书未生效的排查流程

使用以下流程图判断 HTTPS 故障原因：

graph TD
      A[用户访问 https://example.com] --> B{DNS 是否解析正确?}
      B -- 否 --> C[检查 A/CNAME 记录]
      B -- 是 --> D{平台是否已绑定域名?}
      D -- 否 --> E[在 GitHub/Netlify 添加域名]
      D -- 是 --> F{SSL 状态是否为 'Issued'? }
      F -- 否 --> G[等待证书签发或手动重试]
      F -- 是 --> H[检查浏览器是否缓存 HTTP 版本]
      H --> I[清除缓存或使用隐身模式测试]

若长时间未签发，可在 Netlify 手动点击 "Renew certificate"。

5. 资源路径错误（CSS/JS 404）的根本原因与修复

当 base 配置与实际部署路径不匹配时，VitePress 生成的资源引用路径错误。例如：

• 配置 base: '/'，但部署在 https://user.github.io/repo/，资源请求为 /assets/index.xxx.js，实际应为 /repo/assets/...。
• 解决方法：根据部署环境动态设置 base：

// vitepress/config.js
const BASE_PATH = process.env.DEPLOY_ENV === 'github' ? '/your-repo/' : '/';

export default {
  base: BASE_PATH,
  // 其他配置...
}

结合 CI/CD 环境变量实现多环境适配。

6. 高级实践：自动化构建与域名配置一致性保障

为避免人为配置失误，建议在 CI/CD 流程中集成校验逻辑：

# .github/workflows/deploy.yml
jobs:
  deploy:
    steps:
      - name: Validate base config
        run: |
          if [[ $DEPLOY_TARGET == "github" ]]; then
            grep -q "base: '/your-repo/'" vitepress/config.js || exit 1
          fi
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

通过脚本确保 base 与部署目标一致，减少线上故障。

7. 多平台差异对比与最佳实践建议

平台	HTTPS 支持	自定义域名延迟	根域支持	推荐场景
GitHub Pages	自动（Let's Encrypt）	5-30 分钟	需 CNAME + A 记录	开源项目文档
Netlify	自动且强制	即时解析，证书稍等	完全支持	企业级文档站
Vercel	自动签发	快速	支持	高性能要求站点

选择平台时需综合考虑域名管理便利性与 HTTPS 自动化程度。

8. 常见陷阱与调试技巧

开发者常忽略以下细节：

• .nojekyll 文件缺失：GitHub Pages 默认启用 Jekyll，需在根目录放置空 .nojekyll 文件以支持 VitePress 输出。
• 缓存误导：浏览器或 CDN 缓存旧版 HTML，导致即使部署成功仍加载错误资源。
• 混合内容警告：页面通过 HTTPS 加载，但资源引用为 HTTP，需确保所有外部链接为 HTTPS。

调试建议：使用 Chrome DevTools 的 Network 面板查看资源请求路径与状态码。