静态托管

Htmlpress 的构建结果就是一个由 .html、.css、 .js 和资源文件组成的普通目录。任何能提供文件目录服务的东西都可以使用。本指南介绍几种常见方式。

构建站点

htmlpress build

输出位于 .htmlpress/build/。把该目录作为文档根目录。htmlpress preview 会在本地以托管平台的方式提供同一份构建。

预渲染与 SPA 回退

每个页面都是一个真实的文件，即以其源文件命名的文件夹中的一个 index.html： guides/build.html 写入 guides/build/index.html，在 /guides/build/ 提供，就像任何静态托管平台响应文件夹 URL 那样。没有客户端路由，因此任何托管平台都不需要 SPA 回退。

值得配置的是未找到页面。每次构建都会在根目录写出一个 404.html（项目自己的，或内置的）；把托管平台的错误页面指向它，这样未知路径会显示站点的布局，而不是托管平台默认的错误页。

nginx

server {
  listen 80;
  server_name docs.example.com;
  root /var/www/docs;
  index index.html;

  # Try the exact file, then a folder's index.html, else the site's 404 page.
  location / {
    try_files $uri $uri/ =404;
  }
  error_page 404 /404.html;
}

每次发布时将 .htmlpress/build/* 复制到 /var/www/docs/。

Caddy

docs.example.com {
  root * /var/www/docs
  file_server
  encode gzip zstd
  handle_errors {
    rewrite * /404.html
    file_server
  }
}

当域名解析到 Caddy 时，它会自动签发 Let's Encrypt 证书。

AWS S3 + CloudFront

标准做法是以 S3 存储桶为源站，前面放 CloudFront：

1. 将 .htmlpress/build/ 上传到 S3 存储桶（aws s3 sync .htmlpress/build/ s3://my-docs --delete）。
2. 将 Static website hosting → Index document 设为 index.html，Error document 设为 404.html。
3. 创建一个指向该存储桶网站端点的 CloudFront 分配。
4. 在 CloudFront 中添加一条 Custom error response，将 404 映射到 /404.html，并保持响应码为 404。
5. 将该分配的默认根对象设为 index.html。

_htmlpress/ 下的文件在每次构建之间保持文件名不变，因此请只做短时间缓存，或在每次发布时使其失效。

Apache

DirectoryIndex index.html
ErrorDocument 404 /404.html

把这些写入文档根目录下的 .htaccess，并将构建放在那里。真实存在的文件和文件夹会被直接提供；其他请求都会得到站点的 404 页面。

其他托管平台

同样的做法适用于 Render Static、Surge、Fly Static、Bunny，或任何带 CDN 的对象存储：上传目录，把域名指向它，并为未知路径提供 404.html。

使用 GitHub Actions 部署

一个最简的 nginx/SSH 示例：

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
      - uses: easingthemes/ssh-deploy@v5
        with:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_KEY }}
          REMOTE_HOST: ${{ secrets.SSH_HOST }}
          REMOTE_USER: ${{ secrets.SSH_USER }}
          SOURCE: .htmlpress/build/
          TARGET: /var/www/docs/
          ARGS: -avzr --delete

对于 S3，把部署步骤换成 aws-actions/configure-aws-credentials + aws s3 sync。

另请参阅

• 站点元数据：site 用于生成绝对 URL 和 sitemap。
• 部署：返回托管平台索引。