hono-builder 镜像文档

镜像概述

hono-builder 是专为 Hono 轻量级 Web 框架设计的构建专用 Docker 镜像，旨在提供标准化、一致的构建环境，简化 Hono 应用从源代码到可部署产物的全流程构建。通过集成 Hono 框架依赖与构建工具链，该镜像可快速完成代码编译、依赖安装、产物打包等操作，适用于开发环境与 CI/CD 流水线。

核心功能与特性

核心功能

• 标准化环境：内置 Node.js (18+/20+)、npm/yarn/pnpm 包管理器及 Hono 框架依赖，确保跨环境构建一致性。
• 多阶段构建支持：支持分离构建环境与运行环境，减小最终部署产物体积。
• 多打包格式：支持输出 Node.js 应用包、Docker 镜像、静态资源包（如 Vercel Edge Functions 格式）等。
• 依赖缓存优化：通过分层缓存机制减少重复依赖安装，提升构建效率。
• 框架无缝集成：原生适配 Hono 的路由解析、中间件处理等特性，确保构建兼容性。

特性亮点

• 零配置启动：默认适配标准 Hono 项目结构，无需额外配置即可启动构建。
• 灵活参数控制：支持通过环境变量自定义构建行为（如输出目录、打包类型等）。
• CI/CD 友好：轻量级镜像设计，适配 Jenkins、GitHub Actions 等主流流水线工具。

使用场景与适用范围

• 开发团队：本地开发环境快速验证构建流程，统一团队构建标准。
• CI/CD 流水线：作为构建阶段基础镜像，集成到自动化部署流程。
• 多环境部署：针对不同部署目标（如 Node.js 运行时、Serverless 平台）生成对应产物。
• 快速原型开发：简化从代码编写到产物输出的流程，加速验证迭代。

使用方法与配置说明

基本使用（Docker Run）

1. 构建 Node.js 应用包

将 Hono 项目源码挂载至容器，输出 Node.js 应用包至本地目录：

docker run --rm \
  -v $(pwd):/app \          # 挂载本地 Hono 项目目录至容器内 /app
  -v $(pwd)/dist:/output \  # 挂载输出目录，接收构建产物
  hono-builder:latest \
  --pack-type nodejs        # 指定打包类型为 Node.js 应用包

2. 多阶段构建示例（Dockerfile）

通过多阶段构建，使用 hono-builder 生成产物后，基于轻量运行时镜像打包：

# 阶段 1：使用 hono-builder 构建产物
FROM hono-builder:latest AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install  # 利用缓存层优化依赖安装
COPY . .
RUN hono-build --pack-type nodejs --output /app/dist  # 执行构建

# 阶段 2：基于 Node.js 运行时镜像打包部署产物
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./
EXPOSE 3000
CMD ["node", "server.js"]

docker-compose 配置示例

version: '3.8'
services:
  builder:
    image: hono-builder:latest
    volumes:
      - ./:/app:ro           # 只读挂载源码目录
      - ./build-output:/output  # 输出目录
    environment:
      - PACK_TYPE=nodejs     # 打包类型（nodejs/static/edge）
      - CACHE_DIR=/app/.cache # 依赖缓存目录（需本地挂载持久化）
      - NODE_ENV=production  # 构建环境（production/development）

配置参数说明

环境变量

命令行参数

注意事项

• 本地开发时，建议将 CACHE_DIR 挂载至本地目录（如 -v $(pwd)/.hono-cache:/tmp/hono-cache），避免重复安装依赖。
• 构建静态资源包（PACK_TYPE=static）时，需确保 Hono 项目配置了静态资源输出路径（如 app.use('/static', serveStatic({ root: './public' }))）。
• 如需自定义构建命令，可通过挂载 hono-build.config.js 至 /app 目录覆盖默认配置。