使用 Dokploy 和 Nixpacks 部署 Astro 项目并启用缓存优化构建速度

一、Dokploy 配置

Dokploy 是一个开源、可自托管的部署平台，作为 Heroku、Vercel 和 Netlify 的免费替代方案而设计，构建于 Docker 和 Traefik 之上。

1. 创建新项目并连接 GitHub 仓库

2. 设置环境变量

NIXPACKS_NODE_VERSION=22
NIXPACKS_PNPM_STORE_PATH=/root/.local/share/pnpm/store/v3
NIXPACKS_INSTALL_CACHE_DIRS=/app/node_modules
NIXPACKS_BUILD_CACHE_DIRS=/app/node_modules/.cache,/app/astro_cache

3. 关闭缓存清理

项目服务 → Clean Cache：关闭
Web Server → Daily Docker Cleanup：关闭

二、Nixpacks 构建引擎

Nixpacks 是由 Railway 推出的开源构建工具，可将源代码构建为标准 Docker 镜像。Dokploy 使用 Nixpacks 作为默认构建引擎，支持在nixpacks.toml或nixpacks.json文件中指定构建配置。在项目根目录创建 nixpacks.toml 文件，并配置相关的缓存目录。

配置优先级（低 → 高）：

Provider 默认逻辑
nixpacks.toml
环境变量
CLI 参数

常用环境变量

变量名	说明
`NIXPACKS_INSTALL_CMD`	自定义安装命令
`NIXPACKS_BUILD_CMD`	自定义构建命令
`NIXPACKS_START_CMD`	自定义启动命令
`NIXPACKS_PKGS`	安装额外 Nix 包
`NIXPACKS_APT_PKGS`	安装额外 Apt 包
`NIXPACKS_INSTALL_CACHE_DIRS`	安装阶段缓存目录
`NIXPACKS_BUILD_CACHE_DIRS`	构建阶段缓存目录
`NIXPACKS_NO_CACHE`	禁用缓存（不推荐）
`NIXPACKS_CONFIG_FILE`	指定配置文件
`NIXPACKS_DEBIAN`	启用 Debian 基础镜像

三、Astro 项目配置

Astro 是一个面向内容网站的现代 Web 框架，特别适用于博客、营销页与电商等静态网站。当网站有大量图片和静态资源时，构建速度可能会受到影响。通过启用缓存机制，可以显著提升构建效率。

1. 配置构建缓存产物的目录：

Astro 项目需要在配置文件中指定缓存目录，以便在后续构建中复用先前的构建产物。该目录中的文件将在后续构建中使用，以加快构建时间。这个值可以是绝对路径，也可以是相对路径。

//`astro.config.mjs`
export default defineConfig({
  cacheDir: './astro_cache',
});

2. Nixpacks 缓存配置文件

在Astro项目根目录创建 nixpacks.toml 文件，并配置缓存目录和构建命令。

# 使用指定 Node.js 与 pnpm 版本
[phases.setup]
nixPkgs = ["nodejs_22", "pnpm"]

# 安装依赖，并启用 pnpm 缓存
[phases.install]
cmds = ["pnpm install --frozen-lockfile"]
cacheDirectories = ["/root/.local/share/pnpm/store/v3"]

# 构建 Astro 项目，并缓存 node_modules/.cache 与 astro_cache
[phases.build]
cmds = ["pnpm run build"]
cacheDirectories = [
  "node_modules/.cache",
  "astro_cache"
]

# 启动命令（你使用 NGINX 提供 dist 静态目录，此处仅作占位）
[start]
cmd = "echo '构建完成，请通过 NGINX 访问 dist 目录'"

3. 优化 Docker 构建上下文

Astro 项目根目录添加 .dockerignore：

node_modules
astro_cache
dist
*.log
.DS_Store
.vscode
.env*

四、部署与验证

在 Dokploy 自动部署后，请重点检查构建日志中是否包含以下内容，以确认缓存生效：

1. 构建命令使用了挂载缓存

RUN --mount=type=cache,id=xxxx-node_modules/cache,target=/app/node_modules/.cache \
    --mount=type=cache,id=xxxx-astro_cache,target=/app/astro_cache \
    pnpm run build

2. Astro 构建中复用了缓存条目（特别是图片优化）

▶ /_astro/202409272055577_Z2smeTW.avif (reused cache entry)
▶ /_astro/202409272055575_Z2wPyJN.avif (reused cache entry)
▶ /_astro/202409272055577_1IgP6g.avif (reused cache entry)