# Vercel

> 通过 Vercel 的 git 集成或 CLI 部署，每个 PR 都有预览 URL。

Vercel 无法识别 htmlpress 项目，也猜不出它的构建目录。只需一个小小的 `vercel.json` 即可。

## 构建站点

```sh
htmlpress build
```

输出位于 `.htmlpress/build/`。

## 配置 `vercel.json`

将以下内容放在项目根目录，让 Vercel 使用正确的命令并提供正确的目录：

```
{
  "framework": null,
  "buildCommand": "npx gethtmlpress build",
  "outputDirectory": ".htmlpress/build"
}
```

这就是全部配置：此后 Vercel 会负责安装、构建和静态服务，并用构建产出的 `404.html` 响应未知路径。Vercel 会忽略 `_headers`；请改在 `vercel.json` 中设置响应头。

## 通过 git 集成部署

推荐方式：在 [vercel.com/new](https://vercel.com/new) 导入你的仓库。Vercel 会读取 `vercel.json`，运行与你本地相同的构建。每次推送到 `main` 都会发布到生产环境；其他每个分支和 PR 都会获得独立的预览 URL。

## 通过 CLI 部署

用于一次性或脚本化部署：

```
vercel deploy --prod
```

首次运行时会提示执行 `vercel login`，并把目录关联到一个 Vercel 项目。Vercel 会自行运行 `buildCommand`。

## 使用 GitHub Actions 部署

Vercel 的 git 集成本身通常已经足够，但你也可以让部署以 CI 测试为前提：

```yaml
name: deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx gethtmlpress build --json
      - run: npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
```

当某个页面构建失败时，第一个 `run` 会在部署之前让任务失败。你需要把 `VERCEL_TOKEN`、`VERCEL_ORG_ID` 和 `VERCEL_PROJECT_ID` 设为密钥（后两者在首次本地执行 `vercel link` 后位于 `.vercel/project.json` 中）。

## 自定义域名

在项目控制台中，进入 **Settings → Domains → Add**。Vercel 会引导你完成 DNS 记录配置，并自动签发证书。在 `htmlpress.yaml` 中把同一域名设为 `site`。

## 另请参阅

- [站点元数据](/zh/customization/site-metadata/)：`site` 用于填充 sitemap 中的 URL。
- [部署](/zh/deployment/)：返回托管平台索引。