zeabur-dockerfile

Zeabur Dockerfile 生成

始终使用 npx zeabur@latest 调用 Zeabur CLI。 切勿直接使用 zeabur 或通过其他方式安装。如果没有 npx，请先安装 Node.js。

将源代码部署到 Zeabur 时，必须生成 Dockerfile。本技能介绍如何分析项目并生成正确且可部署的 Dockerfile。

先决条件

生成 Dockerfile 前，请先阅读项目的关键文件：

语言	要阅读的文件
Node.js	package.json、锁文件（package-lock.json / yarn.lock / pnpm-lock.yaml）
Python	requirements.txt、Pipfile、pyproject.toml
Go	go.mod
Rust	Cargo.toml
PHP	composer.json
Ruby	Gemfile
Java	pom.xml、build.gradle
.NET	*.csproj、*.sln
Elixir	mix.exs

另请检查：

• 是否已有 Dockerfile 或 docker-compose.yml
• 构建配置（vite.config.js、webpack.config.js、next.config.js 等）
• 是否有 .env.example 文件列出必需的环境变量

不要读取的内容 — 跳过以下内容以节省令牌：

• HTML 文件 — 静态资源，不会影响部署逻辑
• 锁文件内容 — 只检查哪些锁文件存在（以确定包管理器）。不要解析文件内容。
• Markdown 文件 — 仅用于文档，不会影响 Dockerfile 的决策

工作流

1. 分析项目

根据先决条件中的文件，确定：

1. 编程语言和版本
2. 框架（如有）
3. 包管理器
4. 构建命令
5. 启动命令
6. 应用监听的端口
7. 静态站点还是服务端应用

2. 生成 Dockerfile

通用规则

• Dockerfile 中不要写注释
• 不要使用 ENV 或 ARG 指令（框架要求时除外 — 请参见语言专属章节）
• 添加 LABEL "language"="<lang>" — 可用值：nodejs、python、go、static、ruby、java、php、rust、dotnet、elixir、swift、bun
• 仅针对实际的 Web 框架添加 LABEL "framework"="<framework>"（见下方列表）
• 运行任何安装或构建命令前，始终先执行 COPY . .
• 除非用户另有指定，否则设置 WORKDIR /src
• 为应用监听的端口添加 EXPOSE
• 除非构建镜像与运行时镜像不同（例如使用 Node.js 构建，再使用 zeabur/caddy-static 提供服务），否则不要使用多阶段构建

框架与包 — 仅以下项目添加框架标签

框架（使用 LABEL "framework"="..."）： vite、create-react-app、next.js、remix、nuxt.js、umi、nest.js、hexo、vitepress、astro、sli.dev、docusaurus、nitropack、hono、medusa、svelte、flask、django、fastapi、spring-boot、laravel、thinkphp、rails、aspnet、blazorwasm、elysia、baojs

切勿标记为框架（这些是包或库）：

• Python：gradio、pandas、numpy、requests、matplotlib、scikit-learn、tensorflow、pytorch、opencv、pillow、beautifulsoup4、selenium
• Node.js：express、koa、hapi、fastify、socket.io、moment、lodash、axios
• 其他：bootstrap、jquery、chart.js、three.js、d3.js

如果不确定某个项目属于框架还是包，请勿添加框架标签。

静态站点 — zeabur/caddy-static

对于纯静态网站（Vite、静态 Astro、Docusaurus、纯 HTML），请使用 zeabur/caddy-static：

FROM node:22-slim AS build
LABEL "language"="nodejs"
LABEL "framework"="vite"
WORKDIR /src
COPY . .
RUN npm install
RUN npm run build

FROM zeabur/caddy-static
COPY --from=build /src/dist /usr/share/caddy

zeabur/caddy-static 的规则：

• 将构建产物复制到 /usr/share/caddy
• 不要添加 CMD 或 ENTRYPOINT — 镜像会负责处理
• 监听端口 8080
• 仅用于真正的静态站点。不要用于 SSR 框架（Next.js、Nuxt.js、SvelteKit 等）
• 如果使用 Node.js 构建后以静态方式提供服务，请设置 LABEL "language"="nodejs"（而非 "static"）

Node.js

• 默认基础镜像：node:22-slim
• 根据锁文件判断包管理器：

锁文件	包管理器	安装命令
package-lock.json	npm	npm install
yarn.lock	yarn	yarn install
pnpm-lock.yaml	pnpm	RUN npm install -g pnpm && pnpm install

• 使用 npm 时，请使用 npm install。不要使用 npm ci 或 --only=production、--omit=dev、--frozen-lockfile 等标志。
• 对于 Vite 静态站点（React、Vue 静态构建），使用 zeabur/caddy-static 提供服务。
• 对于使用 SSR 框架（SvelteKit）的 Vite 项目，使用 Node.js 运行时。

Next.js — Zeabur 会向容器注入 PORT=8080，因此 Next.js 生产模式默认监听 8080。无需额外配置。

FROM node:22-slim
LABEL "language"="nodejs"
LABEL "framework"="next.js"
WORKDIR /src
COPY . .
RUN npm install
RUN npm run build
EXPOSE 8080
CMD ["npm", "start"]

Svelte / SvelteKit — 使用 node:22（不要使用 alpine 或 slim）。设置 ENV PORT=8080。使用单阶段构建——不要使用 zeabur/caddy-static。不要使用 cross-env ADAPTER=static 或适配器专用构建命令。

FROM node:22
LABEL "language"="nodejs"
LABEL "framework"="svelte"
ENV PORT=8080
WORKDIR /src
RUN npm install -g pnpm@9
COPY . .
RUN pnpm install
RUN pnpm build
EXPOSE 8080
CMD ["pnpm", "start"]

Python

• 默认基础镜像：python:3.10

Flask — 首先找到 WSGI 入口。例如，如果 main.py 包含 app = Flask(__name__)，则入口为 main:app。

FROM python:3.10
LABEL "language"="python"
LABEL "framework"="flask"
WORKDIR /src
COPY . .
RUN pip install -r requirements.txt gunicorn
EXPOSE 8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "main:app"]

FastAPI — 根据现有内容选择启动方式：

1. 如果 requirements.txt 中有 fastapi-cli → fastapi run
2. 如果某个 .py 文件中存在 if __name__ == "__main__": → python <file>.py
3. 否则 → uvicorn main:app --host 0.0.0.0 --port 8080（如果缺少则安装 uvicorn）

FROM python:3.10
LABEL "language"="python"
LABEL "framework"="fastapi"
WORKDIR /src
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

通用 Python — 如果可能适用 WSGI，请使用 gunicorn。如果不确定，直接使用 python <file>.py。

Go

FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN go build -o /app .

FROM debian:bookworm-slim
LABEL "language"="go"
COPY --from=build /app /app
EXPOSE 8080
CMD ["/app"]

PHP（Laravel / Symfony / 通用）

使用 NGINX + PHP-FPM。根据需要调整 PHP 版本和扩展。

FROM php:8.3-fpm
LABEL "language"="php"
WORKDIR /var/www
ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
RUN chmod +x /usr/local/bin/install-php-extensions && sync
RUN apt update && apt install -y cron curl gettext git grep libicu-dev nginx pkg-config unzip && rm -rf /var/lib/apt/lists/*
RUN install-php-extensions @composer apcu bcmath gd intl mysqli opcache pcntl pdo_mysql sysvsem zip
RUN cat <<'NGINX' > /etc/nginx/sites-enabled/default
server {
    listen 8080;
    root /var/www;
    index index.php index.html;
    charset utf-8;
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt { access_log off; log_not_found off; }
    error_page 404 /index.php;
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }
    location ~ /\.(?!well-known).* { deny all; }
    error_log /dev/stderr;
    access_log /dev/stderr;
}
NGINX
RUN chown -R www-data:www-data /var/www
COPY --chown=www-data:www-data . /var/www
USER www-data
RUN if [ -f composer.json ]; then composer install --optimize-autoloader --classmap-authoritative --no-dev; fi && if [ -f package.json ]; then npm install; fi
USER root
EXPOSE 8080
CMD ["sh", "-c", "php-fpm -D && nginx -g 'daemon off;'"]

对于 Laravel，请在 composer install 后添加优化步骤：

RUN php artisan config:cache && php artisan route:cache && php artisan view:cache

3. 处理现有 Dockerfile

• 首先分析现有 Dockerfile
• 如果看起来正确，就原样使用
• 仅在存在问题时（端口错误、缺少依赖等）建议改进
• 如果缺少 Zeabur 专用标签，始终添加 language、framework 标签

CLI 命令

生成 Dockerfile 后，使用以下命令部署：

npx zeabur@latest deploy --project-id <project-id> --json

重新部署时（必须传入服务 ID，以免创建重复服务）：

npx zeabur@latest deploy --project-id <project-id> --service-id <service-id> --json

使用 zeabur-deploy 技能完成完整部署工作流。

错误处理

如果构建或运行时失败：

1. 使用 zeabur-deployment-logs 技能检查构建日志
2. 常见问题：
   • 缺少依赖 — 将依赖添加到 RUN 安装步骤
   • 端口错误 — 确认 EXPOSE 与应用监听的端口一致；使用 zeabur-port-mismatch 技能检查
   • 启动命令错误 — 确认 CMD 与项目的实际入口点一致
   • 将静态站点作为 SSR 提供服务 — 如果应用生成静态输出，请切换到 zeabur/caddy-static
   • 将 SSR 作为静态内容提供服务 — 如果应用需要服务器，请切换到 Node.js 运行时
3. 修复 Dockerfile，然后使用 --service-id 重新部署，以更新现有服务