@gebit/stax-cli

中文文档
1.12.1发布于 2026/11/09GPL-3.0-onlyES Module构建来源已验证近 30 天下载 2150

脚手架, 扩展和验证 stax 堆栈框架的项目

中文使用文档
文档目录6 节
  1. stax init
  2. stax add
  3. stax validate config
  4. folder 需要时间
  5. 发展
  6. 释放

语法 CLI

脚手架,扩展并验证了税堆框架的项目. 软件包 @gebit/stax-cli二进制 stax。需要节点24或稍后.

npm install -g @gebit/stax-cli

stax init

在仓库中生成一个部署包和一个空堆栈列表 :

文件内容
.github/workflows/deploy.yml手动 Deploy 工作流程调用 a-wf-setup-ci.yml 财务报告和审定财务报表 a-wf-deploy-levels.yml 从 GEBITSolutions/stax 在已安装的 CLI 版本中, 匹配 actions-version 投入
configs/default.yaml一个评论 deployment 块以它的 GitHub 变量列出每个需要的部署值(deployment.project 只有当 --project (已给出), stacks: [],评论示例和a yaml-language-server 编辑器在同一版本完成的图解链接
stax init [directory] [--environment <github-environment>] [--project <name>] [--force] [--framework-ref <tag-or-commit-sha>]

stax init 从来没有提示. --environment 财务报告和审定财务报表 --project 是可选的.

已安装的 CLI 版本设置了两个可重复使用的工作流程 refs, 两者均 actions-version 输入和编辑器计划 URL。 全球和项目局部安装使用同样的规则. 使用符合您部署的框架版本的 CLI 发布; init 不更新已有的配置或工作流程.

--framework-ref 仅需用于建设发展大楼0.0.0-development) (中文(简体) ). 给它一个标记, 承诺SHA或分支,包括 main 如果你选择明确跟踪它。 开发建筑不默认为 main拒绝发布 CLI 发布 --framework-ref 并使用自己的准确版本.

  • --environment:默认的 GitHub 环境预选在部署格式中 。 没有它,表格没有预选.
  • --project:小写字母,数字和连字符,从字母开始. 保存为 deployment.project 内 configs/default.yaml;没有它, GitHub 变量 PROJECT 提供值.
  • 没有要求部署值。 生成的配置在一个块中列出所有需要的配置,每个块在它的GitHub变量旁边. 设置它们至少为 GitHub 变量( 存储器或环境); 配置中未注释的值覆盖变量 .
  • 除非 --force 给出。 没有它,什么都没有写.

没有部署直到 configs/default.yaml 至少有一个堆栈; 添加一个 stax add。在部署前在 YAML 或匹配的 GitHub 变量中设置所需的 Azure 资源、 DNS 和状态部署值;参见 部署配置。 。 。 .

生成的呼叫器包括 pages: write 财务报告和审定财务报表 id-token: write gitHub 页面堆栈。 升级到网页化框架的现有呼叫者必须添加 pages: write 因此嵌入式工作流程验证成功。 只使用 Pages 调用程序可以使用设置工作流程 skip-azure-credentials-validation: true; 见存储器的专用 configs/stax-docs.yaml 财务报告和审定财务报表 .github/workflows/docs.yml 实例.

stax add

在配置中添加堆栈 configs/数字 :

stax add [directory] [--config <name>] [--name <stack name>] [--type <type>] [--yes]
  • --config数字 : configs/<name>.yaml,部署工作流程的名称。 没有它,就提供了现有的配置。 与 --yes, (中文(简体) ), default (或作所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出.
  • --name:显示名称. id从中衍生出: 小写字母和数字由破折号相接,外加六个随机数字,例如. Network Hub → network-hub-482913. id只是标识符;它没有任何路径.
  • --type: 计划中的堆栈类型之一; 缺少时作为列表提供.
  • 字段所需的类型被提示, 默认为计划示例( S)folder 默认名称的 sult ). --yes 接受默认值.
  • 该类型所读取的所有其他字段都作为评论性例子加上其说明. 解开你需要的东西.
  • 堆栈在上个堆栈后附加;其余文件保留字节为字节. 使配置无效的堆栈( 如秒) github-pages-site-deploy 堆栈)没有写入.
  • 没有终端,缺失的值就是出错.

字段列表和示例来自 schema: 每个堆栈属性列出读取的类型 x-stax-types (单位:千美元)"all" 及其实例,以 examples。 。 。 .

stax add 读取已安装的 CLI 捆绑的图案。 它在线下工作,而不获取编辑器的图案 URL configs/default.yaml。 。 。 .

stax validate config

检查设置配置与计划 schema/deploy-config.schema.json 并且违反管道执行的规则.

校验读出与已安装的 CLI 捆绑的 schema ,而不是编辑器 schema URL 。 它工作离线; 匹配您安装的 CLI 与您部署的框架版本 .

stax validate config                 # deploy configs directly in configs/
stax validate config -r              # ... and in its subdirectories
stax validate config configs/prod.yaml
stax validate config other-dir -r --strict
  • [path] 是文件或目录;默认为 configs。命名文件总是被验证。 当扫描目录时, YAML 文件不用 deployment, (中文(简体) ), stacks, (中文(简体) ), externalRepos 或者说 globals (例如Helm值)被列为跳过.
  • 调查结果显示 line:column、严重程度和实地路径,例如:. stacks[1].type。 。 。 .
  • 当任何文件出错时退出代码 1; 警告仅失败 --strict。 。 。 .
  • deployment 字段在本地验证中是可选的,因为 GitHub 变量可以提供它们。 在解析后设置检查所需的值 。 未知的部署密钥失败验证, 因为设置拒绝它们 .
错误( 管道失败或悄悄跳过堆栈)警告
无效的 YAML; 错误的字段类型( 如 . local_backend: "false" 而不是布尔)字段( 通常为: depend_on(中文(简体) )
失踪 id 或者说 type; 不详 type; 多个 github-pages-site-deploy 堆栈或 destroy 打开depends_on 或者说 stack.<id>.var.<key> 指向另一个配置中的堆栈
特定类型所需字段: folder 页:1 terraform编号 :opentofu编号 :function-build-deploy包装器 packer_directory编号 :packer_version, (中文(简体) ), s3-site-deploy location, (中文(简体) ), script script, (中文(简体) ), bizep template, (中文(简体) ), function-build-deploy runtimesource_repo 此文件中未定义的别名( 配置一起部署 ) externalRepos(中文(简体) )
绝对的包装路径, 包含 ..,后鞭打,空段或控制字符;非精确 packer_version· ; build_target: hetzner 无 hetzner; 不同构建目标的目的地字段( 也被部署设置拒绝)没有定义堆栈; 已贬值的图片库别名( N)gallery_name 和其他顶级画廊; build_target: aws (保留,工作流程拒绝)
复制堆栈 ID; 格式错误 stack.<id>.var.<key> 参考文献
依赖周期(包括通过 stack.<id>... (a) 依赖链深度超过14级

folder 需要时间

terraform, (中文(简体) ), opentofu 财务报告和审定财务报表 function-build-deploy 堆栈必须设置 folder: 下面的堆栈目录 stack_base_path (默认) terraform/stacks)或以下 functions/。输油管不再倒入堆栈 ID 中,没有 folder。要迁移一个依赖倒数的堆栈,请添加 folder: <its id>。 。 。 .

发展

cd cli
npm ci
npm run typecheck
npm test            # copies ../schema first
npm run build
npm run sync-schema && node src/cli.ts validate config ../path/to/configs   # runs from source (Node 24 type stripping)

对于开发建设,在启动项目时选择一个框架参考,例如 node src/cli.ts init ../my-project --framework-ref main (或 stax init ../my-project --framework-ref main 之后 npm link) (中文(简体) ). 释放的CLI不需要反驳,并拒绝这个选项.

释放

CLI与可再使用的工作流程一起发布,在同一版本下. release.yml 跑在每一个推 main 并构成 a-wf-release-* 相位工作流程 :

  1. a-wf-release-version.yml 等待批准,并从常规承诺中获得下一个版本.
  2. cli-pack.yml 将软件包版本设定为该版本,进行打字检查,测试,构建并打包CLI.
  3. a-wf-release-prepare.yml 执行释放更改,创建标记和预放,并附加已包装的柏油球.
  4. a-wf-release-approve.yml 等待第二次批准(publish-release (b) 环境.
  5. docs.yml 部署文档网站;如果失败,则不发布任何信息.
  6. a-wf-release-publish.yml 发布发布.
  7. cli-publish.yml 运行 npm publish 在同一个球上.

出版使用npm可信任的出版(OIDC):没有npm令牌被存储,npm附加出处证明. 这个 version 内 package.json 留下来 0.0.0-development;只有已出版的软件包携带真实版本.

版本与发布记录

@gebit/stax-cli 共发布 15 个版本,首次发布于 2026/10/20;过去 12 个月发布了 15 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.12.1latest2026/11/097 天前
1.12.02026/11/097 天前
1.11.02026/11/079 天前
1.10.02026/11/079 天前
1.9.02026/11/079 天前
1.8.02026/10/3016 天前

其他发布通道:bootstrap → 0.0.0-bootstrap.0。

关于 @gebit/stax-cli 的常见问题

@gebit/stax-cli 是什么?

脚手架, 扩展和验证 stax 堆栈框架的项目

如何安装 @gebit/stax-cli?

在项目目录运行 npm install @gebit/stax-cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 stax,可以用 npx stax 直接运行。

@gebit/stax-cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gebit__stax-cli 是否存在。

@gebit/stax-cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gebit/stax-cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gebit/stax-cli 可以商用吗?

@gebit/stax-cli 使用 GPL-3.0-only 许可。强 Copyleft:分发包含该代码的软件时,整个作品需以 GPL-3.0 兼容许可开源,并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括,不构成法律意见,请以许可原文为准。

@gebit/stax-cli 的下载量有多少?

根据 npm 官方下载统计,@gebit/stax-cli 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,150 次,日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gebit/stax-cli 还在维护吗?

最新版本 1.12.1 发布于 2026/11/09(7 天前);至今共发布 15 个版本,其中过去 12 个月发布了 15 个;首次发布于 2026/10/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。