Mizuki主题官方文档

外观

部署

约 1948 字大约 6 分钟

2025-08-17

部署到 Vercel

你可以通过 Vercel 的网站 UI 或使用 Vercel 提供的官方 CLI（命令行界面）部署 Astro 站点到 Vercel。部署静态站点和按需渲染站点的过程相同。

通过网站UI部署

  1. 将你的代码推送到你的在线 Git 存储库（GitHub、GitLab、BitBucket 等）.

  2. 导入你的项目 至 Vercel.

  3. Vercel 将自动检测 Astro 项目并自动为其配置正确的设置.

  4. 你的应用程序已部署完成了！（例如：astro.vercel.app）

在你的项目完成导入和部署后，所有后续内容推送到（生产分支外的）分支都将自动生成 预览部署（Preview Deployments），以及对生产分支（通常是名为“main”的分支）所做的任何更改都将自动被部署为 生产部署（Production Deployment）。

通过 CLI 部署(推荐)

  1. 安装Vercel CLI并运行vercel进行部署
    pnpm add -g vercel
vercel
  2. Vercel 将自动检测 Astro 项目并自动为其配置正确的设置.
  3. 当被问及Want to override the settings? [y/N]（想要覆盖配置吗？），选择 N（No）。
  4. 你的应用程序已部署完成了！（例如：astro.vercel.app）

使用 vercel.json 的项目配置

你可以使用 vercel.json 来覆盖 Vercel 的默认行为并配置其他设置。例如，你可以在部署时为 HTTP 响应附加标头。

详细请参考 Vercel 文档的项目配置

部署到 Netlify

Netlify 也是一个流行的静态网站托管平台。您可以直接从 GitHub 部署您的 Mizuki 博客。Netlify 会自动构建和部署您的项目，并提供持续部署功能。

网站用户操作界面部署方式

如果你的项目存储在 GitHub、GitLab、BitBucket 或 Azure DevOps 中，你可以使用 Netlify 的网站用户操作界面来部署你的 Astro 网站.

  1. 在 Netlify dashboard 页面上，点击 Add a new site

  2. 选择 Import an existing project

    当你从你的 Git 提供商中导入 Astro 仓库时，Netlify 应该会自动检测并预填充正确的配置设置。

  3. 确保已输入以下设置，然后按下 Deploy 按钮：

    • Build Command: astro build or npm run build
    • Publish directory: dist

  4. 部署后，你将被重定向到站点概览页面。在那里，你可以编辑你站点的详细信息。

根据你的部署配置，未来对源代码库的任何修改都将触发预览和生产部署。

netlify.toml 文件

你可以选择在项目仓库的顶层创建一个新的 netlify.toml 文件，用来配置你的构建命令和发布目录，以及其他项目设置，包括环境变量和重定向。Netlify 将读取此文件并自动配置你的部署。

为了配置默认设置，创建一个 netlify.toml 文件，并填入以下内容：

[build]
  command = "npm run build"
  publish = "dist"

更多信息可以在 Netlify 的博客文章 部署现有的 Astro Git 仓库 中找到。

CLI 部署方式

你也可以在 Netlify 上创建一个新的站点，并通过安装和使用 Netlify CLI 来关联你的 Git 仓库。

  1. 全局安装 Netlify CLI 工具

    npm install --global netlify-cli

  2. 运行 netlify login 并按照指示进行登录并授权 Netlify。

  3. 运行 netlify init 并按照指示进行操作。

  4. 确认你的构建命令 (astro build)

    CLI 将自动检测构建设置（astro build）和部署目录（dist），并将提供一个自动生成且有这些对应设置的 netlify.toml 文件。

  5. 推送到 Git 来触发构建和部署

    CLI 将向仓库添加一个部署密钥，这意味着每次你使用 git push 时，你的网站都会在 Netlify 上自动重新构建。

更多详情请参阅 Netlify 的文章

部署到 GitHub Pages

如果您希望将博客托管在 GitHub Pages 上，Mizuki 项目通常会包含一个 GitHub Actions 工作流，可以帮助您自动化部署过程。您需要确保在 astro.config.mjs 中配置正确的 base 路径。

部署到 github.io 网址

在 astro.config.mjs 中配置文件设置 site 和 base 选项。

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: 'my-repo',
})

Site

site 的值必须是以下之一：

  • 基于你的用户名的以下网址: https://<username>.github.io
  • 为 GitHub 组织的私有页面 自动生成的随机网址：https://<random-string>.pages.github.io/

提示

如果出现了以下情况，则不要设置 base 参数：

你的页面是由根文件夹所提供。
你的源码存储库是位于 https://github.com/<USERNAME>/<USERNAME>.github.io。

Base

base 的值应该是你的仓库名称，以正斜杠开头，例如 /my-blog。这样做是为了让 Astro 理解你的网站根目录是 /my-repo，而不是默认的 /。

注意

当配置了这个值后，你所有的内部页面链接都必须以你的 base 值作为前缀：

<a href="/my-repo/about">关于本站</a>

查看更多关于配置 base 值的信息。

在 GitHub Pages 上使用自定义域名

设置一个自定义域

你可以选择通过将一个 ./public/CNAME 文件添加到你的项目中，来设置自定义域
这会将你的站点部署在你的自定义域而不是 <YOUR_USERNAME>.github.io。
不要忘记为你的域名提供商配置 DNS。

sub.mydomain.com

要配置 Astro 以在 GitHub Pages 上使用自定义域名，请将你的域名设置为 site 的值。不要为 base 设置值：

import { defineConfig } from 'astro/config'

export default defineConfig({
    site: 'https://example.com',
})

配置 GitHub Action

  1. 在你的项目中的 .github/workflows/ 目录创建一个新文件 deploy.yml，并粘贴以下 YAML 配置信息。
    name: Deploy to GitHub Pages

on:
# 每次推送到 `main` 分支时触发这个“工作流程”
# 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
push:
    branches: [ main ]
# 允许你在 GitHub 上的 Actions 标签中手动触发此“工作流程”
workflow_dispatch:

# 允许 job 克隆 repo 并创建一个 page deployment
permissions:
contents: read
pages: write
id-token: write

jobs:
build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout your repository using git
        uses: actions/checkout@v4
    - name: Install, build, and upload your site
        uses: withastro/action@v3
        # with:
        # path: . # 存储库中 Astro 项目的根位置。（可选）
        # node-version: 20 # 用于构建站点的特定 Node.js 版本，默认为 20。（可选）
        # package-manager: pnpm@latest # 应使用哪个 Node.js 包管理器来安装依赖项和构建站点。会根据存储库中的 lockfile 自动检测。（可选）

deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
    name: github-pages
    url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
  2. （可选）如果你在本地开发期间或预览构建期间，将环境变量传入给 Astro 项目，则需要定义 deploy.yml 文件中的任何公共变量，以便在部署到 Github 页面时处理它们。
    jobs:
build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout your repository using git
        uses: actions/checkout@v4
    - name: Install, build, and upload your site
        uses: withastro/action@v3
        env:
        # 使用单引号来包裹变量值
        PUBLIC_EVM_WALLET_ADDRESS: '0x4bFc229A40d41698154336aFF864f61083E76659'
  3. 在 GitHub 上，跳转到存储库的 Settings 选项卡并找到设置的 Pages 部分。
  4. 选择 GitHub Actions 作为你网站的 Source，然后按 Save。
  5. 选择 GitHub Actions 作为你网站的 Source，然后按 Save。

你的网站现在应该已完成发布了！当你将更改推送到 Astro 项目的存储库时，GitHub Action 将自动为你部署它们。

部署到服务器上

首先我们执行构建命令

npm run build

接下来压缩dist上传到你的服务器上,使用Nginx或者Apache等服务器软件进行部署,静态网站方案即可。