gz-cli-front

v1.0.3

Published

7 days ago

一个轻量级的现代前端脚手架工具

0High
0Medium
0Low

chenhui996

wanderchan

gz-cli-front

一个轻量级的现代前端脚手架工具，支持远程模板和内置模板初始化。

npm 包名为 gz-cli-front，安装后使用 gz-cli 命令。

版本变化统一维护在 gg-cli-docs 更新日志。

安装

npm install -g gz-cli-front

使用

gz-cli init [project-name]

也可以不全局安装，直接运行：

npx gz-cli-front init demo-app

create 命令仍可使用，例如 gz-cli create demo-app。同时保留 gz-cli-front 作为兼容命令，两者执行相同逻辑；新包不注册旧的 gg-cli 命令。

从旧包迁移时可执行：

npm uninstall -g @chenhui996/gg-cli
npm install -g gz-cli-front
gz-cli --version
gz-cli init demo-app

切换 CLI 后，新建项目默认使用当前远程模板；已有业务项目不会自动迁移。

内网初始化

从 1.0.2 起，无法访问 GitHub 时，可使用随 CLI 发布的内置模板。从 1.0.3 起，内网模式也支持主应用模板，安装最新正式版即可使用：

npm install -g gz-cli-front@latest

gz-cli init demo-app --internal
# 简写
gz-cli init demo-app -i

内网模式跳过远程模板列表和模板下载，可选择内置 micro-app 或 main-app，默认选中微应用。 1.0.2 只提供微应用模板。普通模式不会因网络失败自动切换为内网模式， create 兼容命令同样支持此参数。 --internal 与 --refresh 不能同时使用，内置模板随 CLI 版本更新。

生成项目不需要访问 GitHub；CLI 和项目依赖安装仍需可用的 npm 源。初始化时可选择暂不安装依赖，之后在内网配置好的 npm 源下执行 npm install。

本版本验证范围为内网模板选择与项目生成，初始化时可选择暂不安装依赖。主应用沿用源模板的依赖声明和代码；本次验证发现其仍有 npm peer 冲突、TypeScript 和 Lint 问题，尚未通过生产构建。本版本不包含这些问题的修复。

包管理器

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

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

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

网络代理

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

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

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

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

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

模板缓存

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

gz-cli init demo-app --refresh

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

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

可通过 GZ_CLI_FRONT_CACHE_DIR 指定缓存目录，通过 GZ_CLI_FRONT_DEBUG=1 开启网络和模板调试日志。新包不读取旧的 GG_CLI_* 环境变量，也不复用旧包的默认缓存目录。

模板注册仓库由 config/gz-cli-front.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 配置也可继续使用。

更新内置模板

外部 gg-cli-template-micro-app 和 gg-cli-template-main-app 仓库仍是模板维护源。提交模板改动后，在 CLI 仓库按需同步：

npm run sync:template
npm run sync:template:main
npm run test:release

sync:template 同步微应用，sync:template:main 同步主应用；两者独立执行，不会更新另一份快照。同步脚本读取同级模板仓库的已提交版本，仅导出 Git 已跟踪内容到 template/<模板名>，来源 commit 记录在 template/<模板名>.snapshot.json。未提交改动会阻止同步；node_modules、构建产物和本机配置不会从工作目录复制进来。其他位置的仓库可通过 npm run sync:template -- <仓库路径> 或 npm run sync:template:main -- <仓库路径> 指定。

构建时将快照压缩到 dist/template/<模板名>.tar.gz，保留 .gitignore、.npmrc 等模板文件。日常构建和发布只使用仓库中已有的快照，不要求本机存在外部模板仓库。请勿直接修改快照，也不要将旧的 src/template 目录作为内网模板。

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

发布到 npm

本包以 gz-cli-front 为独立包名，初始版本为 1.0.0，不会覆盖或更新旧的 @chenhui996/gg-cli 包。

首次发布前，确认包名尚未被占用，并登录有发布权限的 npm 账号：

npm view gz-cli-front --registry=https://registry.npmjs.org/
npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/

查询返回 E404 表示未找到该包；网络或认证错误不能作为包名可用的判断依据。最终能否发布以 npm 的校验结果为准。

安装依赖并验证：

npm ci
npm run test:release

确认通过后发布：

npm publish --registry=https://registry.npmjs.org/

发布时会自动通过 prepublishOnly 再运行一次发布验证。发布内容包括 bin、构建后的 dist、包信息和 README，不包含 src/template 中的本地模板。

发布后可验证：

npm view gz-cli-front version --registry=https://registry.npmjs.org/
npx --registry=https://registry.npmjs.org/ [email protected] --version

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

gz-cli-front

安装

使用

内网初始化

包管理器

网络代理

模板缓存

更新内置模板

Git 仓库访问测试

发布到 npm