gg-cli

• 一个前端 cli 工具

安装

npm install -g @chenhui996/gg-cli

使用

gg-cli init [project-name]

可通过 --pm 指定本次初始化使用的包管理器：

gg-cli init demo-app --pm npm
gg-cli init demo-app --pm pnpm
gg-cli init demo-app --pm yarn

未指定时，CLI 会按 pnpm、yarn、npm 的顺序检测当前环境；都未检测到时默认使用 npm。模板注册表不包含包管理器配置。

网络代理

CLI 会自动读取当前系统代理，不绑定具体代理工具、地址或端口。代理优先级如下：

--no-proxy 强制直连
--proxy 参数
HTTP_PROXY / HTTPS_PROXY / NO_PROXY
操作系统代理
无代理直连

临时指定代理或强制直连：

gg-cli init demo-app --proxy http://proxy-host:port
gg-cli init demo-app --no-proxy

系统代理检测支持 Windows、macOS 和 Linux。代理相关日志只显示网络路径，不输出代理地址、账号或密码。

模板缓存

模板注册仓库和模板仓库会浅克隆并缓存到 ~/.gg-cli/cache，减少重复创建项目时的网络等待。需要忽略缓存并获取最新内容时执行：

gg-cli init demo-app --refresh

注册表缓存有效期为 5 分钟，latest 模板缓存有效期为 10 分钟；指定版本的模板缓存可以长期复用。远程暂时不可用时，未指定 --refresh 会回退到已有缓存。

模板注册仓库和模板仓库均为公共仓库，默认通过配置中的 HTTPS 地址直接下载，无需配置 GitHub Token 或 SSH Key。Git 操作设有超时并支持网络代理；如显式配置 SSH clone URL，仍会使用本机 SSH Agent。

模板注册仓库由 config/gg-cli.config.json 管理：

{
  "templateRegistry": {
    "source": "git",
    "url": "https://github.com/gz-fronted/gg-cli-template-register.git",
    "file": "templates.json"
  }
}

注册表中的每个模板使用独立仓库，例如：

[
  {
    "name": "main-app",
    "label": "主应用模板",
    "description": "Garfish 主应用模板",
    "type": "main",
    "source": "git",
    "url": "https://github.com/your-org/gg-cli-template-main-app.git",
    "version": "latest"
  },
  {
    "name": "micro-app",
    "label": "微应用模板",
    "description": "Garfish 微应用模板",
    "type": "micro",
    "source": "git",
    "url": "https://github.com/your-org/gg-cli-template-micro-app.git",
    "version": "latest"
  }
]

公共仓库建议使用 source: "git" 和 HTTPS clone URL，避免要求使用者配置 SSH Key。CLI 会按配置的协议执行浅克隆；source 仍兼容 github、gitlab 和 git，旧的 GitHub repo 配置也可继续使用。

Git 仓库访问测试

发版前可以在本机验证 Git 仓库访问失败时的错误提示，不会修改全局 Git 配置：

npm run test:auth-error

该脚本使用独立缓存和模拟失败的 Git 命令运行构建后的 CLI，要求在超时前返回明确错误。正常访问链路仍使用以下命令验证：

npm run build
node dist/index.js init --refresh

发版前统一执行：

npm run test:release

该命令会依次验证构建、HTTPS Git 兼容性、公共注册仓库访问、失败错误提示和 npm 发布包内容。

如果已经手动执行过 npm run build，可以只验证构建产物和 Git 场景：

npm run test:smoke