构建与部署

构建与部署

概述

文档编写完成后，需要构建并部署到托管平台。本节介绍构建流程和主流免费托管平台的部署方法。

问答

Q：如何构建站点？

A：运行构建命令：

npm run build

这会在 dist/ 目录生成静态站点。Astro 会：

1. 处理所有 Markdown/MDX 文件
2. 生成带语法高亮的 HTML 页面
3. 创建站点地图（sitemap-index.xml）
4. 构建搜索索引（Pagefind）
5. 优化 CSS 和 JavaScript

本地预览构建结果：

npm run preview

Q：推荐哪些托管平台？

A：对于静态文档站，以下平台提供性能出色的免费托管：

平台	免费额度	自定义域名	自动部署	适合
Vercel	慷慨	支持	GitHub/GitLab	Astro 项目（原生支持）
Cloudflare Pages	无限	支持	GitHub/GitLab	全球 CDN，无带宽限制
GitHub Pages	1GB 存储	支持	仅 GitHub	简单项目，开源
Netlify	100GB 带宽	支持	GitHub/GitLab	表单处理，边缘函数

Q：如何部署到 Vercel？

A：Vercel 对 Astro 有一等支持：

1. 连接仓库：

   • 访问 vercel.com 并通过 GitHub 登录
   • 点击”New Project”并导入你的仓库

2. 配置项目：

   • Framework Preset: Astro
   • Build Command: npm run build
   • Output Directory: dist

3. 部署：点击”Deploy”，Vercel 会自动构建并发布站点

每次推送到 main 都会触发自动重新部署。Pull Request 会获得预览 URL。

也可使用 Vercel CLI：

npm install -g vercel
vercel --prod

Q：如何部署到 GitHub Pages？

A：使用 GitHub Pages 需要调整 astro.config.mjs：

export default defineConfig({
  site: 'https://yourusername.github.io',
  base: '/repo-name',  // GitHub Pages 必需
  integrations: [starlight({ /* ... */ })],
});

然后添加 GitHub Actions 工作流（.github/workflows/deploy.yml）：

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

在仓库 Settings → Pages → Source 中启用 GitHub Actions。

Q：如何设置自定义域名？

A：大多数托管平台支持自定义域名：

1. 添加域名：在托管平台的控制台中添加（如 Vercel → Project Settings → Domains）
2. 配置 DNS 记录：在域名注册商处设置：

记录类型	名称	值
A	@	76.76.21.21（Vercel）
CNAME	www	cname.vercel-dns.com
CNAME	docs	cname.vercel-dns.com

3. 等待传播（通常 5-30 分钟）
4. HTTPS 由大多数平台自动配置

Q：面向国内用户的部署方案是什么？

A：对于国内用户，考虑以下托管选项：

• Cloudflare Pages：包括亚洲在内的良好 CDN 覆盖
• 阿里云 OSS + CDN：国内最佳性能（需要 ICP 备案）
• 腾讯云 COS + CDN：阿里云的替代方案（同样需要 ICP 备案）

注意：Vercel 和 GitHub Pages 从中国大陆访问可能较慢或不稳定。如果受众主要在国内，建议使用有 ICP 备案的国内托管方案。

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →