ZDSC - NPM 包使用指南

安装

全局安装（推荐）

npm install -g zdsc-deploy

安装后，你可以在任何项目中使用 zdsc 命令。

本地安装

npm install --save-dev zdsc-deploy

然后使用 npx zdsc 或 npm run 来执行命令。

快速开始

1. 初始化配置（交互式向导）

zdsc init

这会启动一个友好的交互式配置向导，引导你完成所有配置：

• 项目名称
• 服务器地址
• SSH 用户名和端口
• 项目类型（前端/后端/自动检测）
• Nginx 配置（前端项目）
• 部署路径等

2. 安装部署脚本到项目

zdsc install

这会将所有必要的脚本文件复制到当前项目。

3. 一键设置（安装脚本 + 配置）

zdsc setup

同时完成脚本安装和配置初始化。

常用命令

构建项目

# 使用默认版本号
zdsc build

# 指定版本号
zdsc build v1.0.0

# 构建并自动部署
zdsc build v1.0.0 --deploy

# 构建并部署到指定服务器
zdsc build v1.0.0 --deploy --server your-server.com

部署项目

# 使用配置中的服务器
zdsc deploy v1.0.0

# 指定服务器
zdsc deploy v1.0.0 your-server.com

# 使用默认版本号
zdsc deploy

查看帮助

zdsc --help
zdsc build --help
zdsc deploy --help

完整工作流示例

# 1. 全局安装工具
npm install -g zdsc-deploy

# 2. 进入你的项目目录
cd /path/to/your-project

# 3. 一键设置（安装脚本 + 配置）
zdsc setup

# 4. 构建并部署
zdsc build v1.0.0 --deploy

就这么简单！

命令说明

zdsc init / zdsc config

启动交互式配置向导，创建或更新 .deploy.env 配置文件。

zdsc install

将部署脚本安装到当前项目：

• build.sh
• deploy.sh
• quick-deploy.sh
• .deploy.env.example
• .github/workflows/deploy.yml
• .gitlab-ci.yml

zdsc setup

一键完成：安装脚本 + 初始化配置。

zdsc build [version]

构建项目。

• version: 版本号（可选，默认使用时间戳）

选项：

• -d, --deploy: 构建后自动部署
• -s, --server <server>: 指定部署服务器

zdsc deploy [version] [server]

部署到生产环境。

• version: 版本号（可选）
• server: 服务器地址（可选，使用配置文件中的值）

配置管理

配置文件位置：.deploy.env

# 查看配置
cat .deploy.env

# 编辑配置
nano .deploy.env

# 重新配置
zdsc init

与 CI/CD 集成

GitHub Actions

工具会自动安装必要的脚本，然后你可以在 GitHub Actions 中直接使用：

- name: Build and Deploy
  run: |
    npm install -g zdsc-deploy
    zdsc build v1.0.0 --deploy

GitLab CI/CD

类似地，在 GitLab CI 中使用：

build:
  script:
    - npm install -g zdsc-deploy
    - zdsc build v1.0.0

优势

✅ 无需手动复制文件 - 一条命令自动安装
✅ 交互式配置 - 友好的向导，无需手动编辑文件
✅ 全局可用 - 安装一次，任何项目都能用
✅ 统一体验 - 所有项目使用相同的工具和流程
✅ 易于更新 - npm update -g zdsc-deploy 即可更新

发布到 npm

如果你想将这个工具发布到 npm：

# 1. 登录 npm
npm login

# 2. 发布
npm publish

# 3. 更新版本后重新发布
npm version patch  # 或 minor, major
npm publish

故障排查

命令不存在

# 检查是否安装
npm list -g zdsc-deploy

# 重新安装
npm install -g zdsc-deploy

# 检查 PATH
echo $PATH  # Linux/Mac
echo %PATH%  # Windows

权限错误

# Linux/Mac: 可能需要 sudo
sudo npm install -g zdsc-deploy

# 或配置 npm 全局目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Windows 问题

在 Windows 上，确保使用 Git Bash 或 PowerShell，而不是 CMD。

更新

npm update -g zdsc-deploy