safe-coal-web-template

一个可以从 Gitee 仓库下载 Vue 项目的脚手架工具（支持公有和私有仓库）。

功能特性

• ✅ 支持从 Gitee 公有/私有仓库下载项目
• ✅ 支持指定分支下载
• ✅ 交互式命令行界面
• ✅ 支持命令行参数快速创建项目
• ✅ 公有仓库无需 token，使用更简单

安装

全局安装

npm install -g safe-coal-web-template

本地安装

npm install safe-coal-web-template

使用前准备

1. 配置默认仓库地址（开发者）

如果你是开发者，需要先配置默认的 Gitee 仓库地址：

编辑 lib/config.js 文件，修改配置：

module.exports = {
  defaultRepo: 'tofuhua/web-template',  // 修改为你的仓库地址（格式: owner/repo）
  defaultBranch: 'master',
  isPublic: true  // true: 公有仓库，false: 私有仓库
};

重要说明：

• defaultRepo: 仓库地址格式为 owner/repo，例如 tofuhua/web-template
• isPublic: 设置为 true 表示公有仓库（无需 token），false 表示私有仓库（需要 token）

2. 获取 Gitee 访问令牌（仅私有仓库需要）

如果使用私有仓库，用户需要先获取 Gitee 的访问令牌：

1. 登录 Gitee
2. 进入 设置 → 安全设置 → 私人令牌
3. 点击 生成新令牌
4. 勾选 projects 权限（至少需要 projects 的读取权限）
5. 生成并复制令牌（只显示一次，请妥善保存）

注意： 公有仓库无需 token，可以直接使用！

使用方法

方式一：公有仓库（最简单）

如果配置的是公有仓库，直接创建项目，无需任何额外操作：

safe-coal-web-template create my-project

就这么简单！无需输入 token。

方式二：私有仓库

如果配置的是私有仓库，创建项目时会提示输入访问令牌：

safe-coal-web-template create my-project

然后按提示输入 Gitee 访问令牌即可。

方式三：使用环境变量（推荐用于 CI/CD，仅私有仓库）

通过环境变量设置访问令牌，无需交互：

# Windows (PowerShell)
$env:GITEE_TOKEN="your-gitee-token"
safe-coal-web-template create my-project

# Windows (CMD)
set GITEE_TOKEN=your-gitee-token
safe-coal-web-template create my-project

# Linux/Mac
export GITEE_TOKEN=your-gitee-token
safe-coal-web-template create my-project

方式四：命令行参数

# 指定分支
safe-coal-web-template create my-project --branch main

# 私有仓库指定 token
safe-coal-web-template create my-project --token your-gitee-token

# 指定其他仓库（会按私有仓库处理）
safe-coal-web-template create my-project \
  --repo other-owner/other-repo \
  --token your-gitee-token

或者使用简写：

safe-coal-web-template create my-project -b main -t your-token

方式五：指定其他仓库

如果需要从其他仓库下载（覆盖默认配置）：

# 从其他公有仓库下载
safe-coal-web-template create my-project --repo owner/public-repo

# 从其他私有仓库下载
safe-coal-web-template create my-project \
  --repo owner/private-repo \
  --token your-gitee-token

参数说明

• project-name: 项目名称（必需）
• -r, --repo <repo>: Gitee 仓库地址，格式：owner/repo（可选，不指定则使用默认仓库）
• -b, --branch <branch>: 分支名称，默认为 master（可选）
• -t, --token <token>: Gitee 访问令牌（仅私有仓库需要，也可通过 GITEE_TOKEN 环境变量设置）

示例

# 公有仓库（最简单，无需 token）
safe-coal-web-template create my-vue-app

# 私有仓库（交互式输入 token）
safe-coal-web-template create my-vue-app

# 使用环境变量（私有仓库，无需交互）
export GITEE_TOKEN=your-token
safe-coal-web-template create my-vue-app

# 指定分支
safe-coal-web-template create my-vue-app --branch main

# 从其他公有仓库下载
safe-coal-web-template create my-vue-app --repo username/public-repo

# 从其他私有仓库下载
safe-coal-web-template create my-vue-app \
  --repo username/private-repo \
  --token your-token

项目结构

safe-coal-web-template/
├── bin/
│   └── cli.js          # CLI 入口文件
├── lib/
│   ├── config.js       # 默认配置（仓库地址等）
│   └── download.js      # 下载逻辑
├── package.json
└── README.md

发布到 npm

1. 登录 npm

npm login

2. 发布

npm publish

3. 更新版本

修改 package.json 中的 version 字段，然后重新发布：

npm version patch  # 补丁版本 1.0.0 -> 1.0.1
npm version minor  # 次要版本 1.0.0 -> 1.1.0
npm version major  # 主要版本 1.0.0 -> 2.0.0
npm publish

注意事项

1. 访问令牌安全：不要将访问令牌提交到代码仓库，建议使用环境变量或交互式输入
2. 仓库权限：确保访问令牌有足够的权限访问目标私有仓库
3. 网络环境：确保能够访问 Gitee（可能需要配置代理）

常见问题

Q: 提示认证失败？

A: 请检查：

• 访问令牌是否正确
• 访问令牌是否已过期
• 访问令牌是否有 projects 权限

Q: 提示仓库不存在？

A: 请检查：

• 仓库地址格式是否正确（应为 owner/repo）
• 访问令牌是否有权限访问该私有仓库
• 仓库是否确实存在

Q: 提示分支不存在？

A: 请检查分支名称是否正确，可以使用 master、main 或其他存在的分支名。

License

MIT