stephaneberle9/node-docker

Node.js Docker镜像文档

镜像概述

Node.js Docker镜像是一个预配置了Node.js运行环境的容器化镜像，基于官方Node.js发行版构建，支持多种基础镜像变体（如Alpine、Debian）。该镜像提供稳定、轻量的Node.js运行环境，可直接用于运行Node.js应用，或作为基础镜像构建自定义应用镜像，适用于从开发测试到生产部署的全流程场景。

核心功能与特性

• 版本可控：提供多版本标签（如18-alpine、20-bullseye），可精确指定Node.js版本，避免环境差异
• 轻量高效：基于Alpine的变体镜像体积小于100MB，Debian变体平衡兼容性与体积
• 工具集成：内置npm/yarn包管理器，支持快速安装依赖
• 多架构支持：兼容amd64、arm64等主流架构，适配不同硬件环境
• 灵活配置：支持环境变量注入、卷挂载、端口映射等Docker标准功能
• 生态兼容：可直接作为CI/CD流程的执行环境，兼容Docker Compose、Kubernetes等编排工具

使用场景

• 本地开发环境：快速搭建与团队一致的Node.js开发环境，避免"在我电脑上能运行"问题
• 自动化测试：作为CI/CD流水线中的测试环境，执行单元测试、集成测试
• 生产部署：直接部署Node.js应用，或作为基础镜像构建包含应用代码的生产镜像
• 教学演示：快速展示Node.js应用运行效果，无需手动配置本地环境

使用方法

1. 基本使用（docker run）

运行交互式REPL

bash
# 拉取指定版本镜像（以Node.js 18 Alpine为例）
docker pull node:18-alpine

# 启动Node.js交互式终端
docker run -it --rm node:18-alpine node

运行本地Node.js应用

bash
# 假设当前目录为应用根目录，包含app.js
docker run -it --rm \
  -v $(pwd):/app \          # 挂载本地代码到容器内/app目录
  -w /app \                 # 设置工作目录为/app
  -p 3000:3000 \            # 映射端口（宿主端口:容器端口）
  node:18-alpine \          # 使用的镜像
  node app.js               # 执行的命令

2. 配置环境变量

通过-e参数注入环境变量，应用内通过process.env访问：

bash
docker run -d \
  --name node-api \
  -e NODE_ENV=production \  # 设置生产环境
  -e API_KEY=secret123 \    # 注入自定义密钥
  -e PORT=4000 \            # 指定应用端口
  -p 4000:4000 \
  -v $(pwd):/app \
  -w /app \
  node:18-alpine \
  node server.js

3. Docker Compose配置

创建docker-compose.yml管理多容器应用：

yaml
version: '3.8'
services:
  node-app:
    image: node:18-alpine
    container_name: node-service
    restart: always  # 异常退出后自动重启
    environment:
      - NODE_ENV=production
      - DB_HOST=mysql  # 连接其他服务（需在同一网络）
      - DB_PORT=3306
    ports:
      - "3000:3000"
    volumes:
      - ./:/app:ro  # 只读挂载代码目录（生产环境推荐）
      - node_modules:/app/node_modules  # 持久化依赖目录
    working_dir: /app
    command: node index.js
    depends_on:
      - mysql  # 依赖mysql服务启动后再启动

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=nodeapp

volumes:
  node_modules:  # 声明命名卷，避免依赖重复下载

启动服务：docker-compose up -d
查看日志：docker-compose logs -f node-app

4. 构建自定义应用镜像

创建Dockerfile将应用代码打包进镜像（生产环境推荐）：

dockerfile
# 基础镜像（选择适合的版本和变体）
FROM node:18-alpine AS builder

# 设置工作目录
WORKDIR /app

# 复制依赖文件并安装（利用Docker层缓存）
COPY package*.json ./
RUN npm ci --only=production  # 仅安装生产依赖

# 复制应用代码
COPY . .

# 暴露应用端口（文档性，需配合-p映射）
EXPOSE 3000

# 启动命令
CMD ["node", "server.js"]

构建镜像：docker build -t my-node-app:1.0 .
运行自定义镜像：docker run -p 3000:3000 my-node-app:1.0

配置参数说明

注意事项

• 版本选择：生产环境务必使用具体版本标签（如node:18.18.2-alpine），避免latest标签自动更新导致兼容性问题
• 安全最佳实践：生产环境建议：
  1. 使用非root用户运行容器（可通过Dockerfile的USER指令配置）
  2. 代码目录设为只读挂载（:ro）
  3. 敏感信息通过Docker Secrets或外部配置中心管理
• 性能优化：Alpine变体体积小但可能缺少部分系统库，若依赖原生模块（如bcrypt），可选用Debian基础的slim或bullseye变体
• 持久化数据：应用数据（如日志、上传文件）建议通过卷挂载到宿主或使用外部存储服务，避免数据随容器删除丢失