easywebci 🚀

一个简单、约定优于配置的 CI/CD 工具，专为现代 Web 项目设计。

easywebci 旨在标准化项目的构建和发布流程，让您可以在不同的 CI/CD 平台（如 GitLab CI, GitHub Actions, Gitee 等）上使用相同的命令完成部署，告别复杂的平台相关脚本。

核心功能

• 一键初始化: 通过 easywebci init 命令快速生成配置文件，上手零门槛。
• 多环境支持: 可为 dev、prod 等不同环境定义独立的构建和发布工作流。
• 灵活的构建流程: 支持自定义包管理器 (npm/yarn/pnpm)，并可自动执行依赖清理和安装。
• 多种发布方式: 内置 scp (支持远程服务器和本地部署) 和 docker (支持多标签构建和清理) 两种发布方式。
• 跨平台构建: Docker 发布默认构建 x86_64 架构的镜像，确保在 ARM 架构（如 Apple Silicon）的开发机上也能构建出兼容生产环境的镜像。
• 平台无关: 无需再编写复杂的 .gitlab-ci.yml 或 main.yml，只需调用 easywebci 命令。
• 安全: 敏感凭证（如密码、私钥、Token）从环境变量中读取，不会硬编码在代码中。
• 消息通知: 内置对飞书和兼容 Slack 的 Webhook 通知支持。

如何安装

在您的 CI/CD 环境中，通��� npm/pnpm/yarn 安装：

npm install -g easywebci

命令详解

easywebci build [环境名]

根据环境配置编译代码（单独运行适用于本地环境）

# 构建 dev 环境
easywebci build

# 构建 prod 环境
easywebci build prod

easywebci publish [环境名]

根据环境配置部署代码（单独运行适用于本地环境）

# 发布 prod 环境
easywebci publish prod

easywebci run [环境名]

根据环境配置，在发布机器上面，run命令完成build、publish等一系列完整的 CI/CD 流程。

# 完整执行 prod 环境的构建和发布
easywebci run prod

配置文件 .easywebci.json

easywebci init

强烈建议从此命令开始。 它会在您项目的根目录下创建一个 .easywebci.json 配置文件模板。您只需要根据注释修改其中的值即可。

easywebci init

通过 easywebci init 生成后，您将得到类似下面的结构。请根据注释修改以适配您的项目。

{
  // "environments" 中定义了不同环境的配置
  "environments": {
    // "dev" 环境：通常用于开发或测试，这里演示了如何部署到本地
    "dev": {
      "build": {
        "packageManager": "yarn", // (可选) 指定包管理器, 支持 "npm", "yarn", "pnpm"。默认为 "yarn"
        "clean": true,            // (可选) 构建前是否删除 node_modules。默认为 false
        "install": true,          // (可选) 构建前是否安装依赖。默认为 true
        "installOption": {        // (可选) 提供额外的安装参数
          "ignoreEngines": true, // (可选) 添加 --ignore-engines 参数
          "registry": "https://registry.npmmirror.com" // (可选) 指定镜像源
        },
        "script": "build:dev"     // (必须) package.json 中定义的构建脚本名
      },
      "publish": {
        "method": "scp",                  // 使用 scp 方式发布
        "buildOutputDir": "dist",         // (必须) 指定构建产物目录
        // "deployHost" 是部署目标。可以是 "localhost", "127.0.0.1" 或 IP/域名
        "deployHost": "localhost",
        // 当 deployHost 为 "localhost" 时, "remoteDeployPath" 是本地的绝对路径
        "remoteDeployPath": "/tmp/my-dev-app"
      }
    },
    // "prod" 环境：通常用于正式生产，这里演示了如何通过 scp 部署到远程服务器
    "prod": {
      "build": {
        "packageManager": "yarn",
        "clean": true,
        "install": true,
        "script": "build:prod",
        // (可选) 指定一个 Node.js 版本, 构建将在对应的 Docker 容器中进行, 保证环境纯净。
        // 如果不指定此字段, 构建将直接在当前机器(CI Runner)的环境中执行。
        "nodeVersion": "18-alpine"
      },
      "publish": {
        "method": "scp",
        "buildOutputDir": "dist",
        "deployHost": "your-prod-server.com", // (必须) 您的生产服务器 IP 或域名
        "hostLoginName": "root",               // (可选) 登录服务器的用户名, 默认为 "root"
        "remoteDeployPath": "/var/www/prod-app" // (必须) 部署到服务器上的绝对路径
      }
    },
    // "prod-docker" 环境：演示如何通过 Docker 发布镜像
    "prod-docker": {
      "build": {
        "packageManager": "yarn",
        "clean": true,
        "install": true,
        "script": "build:prod",
        "nodeVersion": "18-alpine"
      },
      "publish": {
        "method": "docker",
        "platform": "aws",
        "dockerfile": "Dockerfile", // (可选) Dockerfile 路径, 默认为 './Dockerfile'. 它将被自动复制到构建上下文中.
        "dockerBuildContext": "dist", // (可选) Docker build 的上下文目录, 默认为 "dist".
        "imageName": "my-awesome-app",
        "region": "us-east-1"
      }
    }
  },
  // "notification" 用于配置消息通知
  "notification": {
    "method": "feishu", // (可选) 支持 "feishu", "slack"
    // (必须) 你的 Webhook 地址, 建议从环境变量读取以保证安全
    "webhookUrl": "https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-id"
  }
}

easywebci env

检查运行环境是否安装了必需的软件，如 git, docker, aws-cli 等。

easywebci clone

在 CI 环境中准备代码。此命令会强制删除任何已存在的同名目录，然后执行 git clone 来确保每次都获取一个纯净、全新的代码副本。

easywebci notify [环境名]

发送通知。通常在流程执行成功或失败后调用。

# 发送成功的通知
easywebci notify prod --status success

# 发送失败的通知，并附带自定义消息
easywebci notify prod --status failure --message "构建镜像失败"

环境变量

为了安全，请将敏感信息存储在 CI/CD 平台的 "Secrets" 或 "Variables" 中。

scp 发布方式所需变量:

• EASYWEB_PRIVATE_KEY: SSH 私钥的完整内容。(推荐)
• EASYWEB_PASSWORD: 服务器用户密码。(不推荐)

docker 发布方式 (以 AWS ECR 为例):

• AWS_ACCESS_KEY_ID: 您的 AWS Access Key ID。
• AWS_SECRET_ACCESS_KEY: 您的 AWS Secret Access Key。

CI/CD 集成示例

您的 CI/CD 配置文件会变得极其简���。

.gitee-ci.yml 示例:

# 定义流水线的各个阶段
stages:
  - deploy

# 定义一个部署到 dev 环境的任务
deploy_dev:
  stage: deploy
  # 指定使用 Gitee CI 提供的 node:18-alpine 镜像作为构建环境
  image: node:18-alpine
  # 定义只在非 main 分支上触发此任务
  only:
    - /^(?!main|master$).*$/
  script:
    # 安装 easywebci
    - npm install -g easywebci
    # 运行 dev 环境的完整流程
    - easywebci run dev

# 定义一个部署到 prod-docker 环境的任务
deploy_prod_docker:
  stage: deploy
  # 指定使用 docker:latest 镜像, 因为我们需要 docker 命令
  image: docker:latest
  # 定义只在 main 或 master 分支上触发此任务
  only:
    - main
    - master
  script:
    # Gitee 的 docker:latest 镜像中不包含 node, npm, aws-cli, 需要手动安装
    - echo "Installing dependencies..."
    - apk add --no-cache nodejs npm python3 py3-pip
    - pip install awscli
    - npm install -g easywebci
    # 运行 prod-docker 环境的完整流程
    - easywebci run prod-docker