# @gebit/stax-cli 中文文档

规范地址：https://npmcn.com/package/%40gebit/stax-cli/

版本：1\.12\.1
npm 元数据更新时间：2026-11-08T22:18:10.023Z
中文译文更新时间：2026-11-16T01:39:12.200Z
软件包许可：GPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gebit/stax-cli
原文对照：https://npmcn.com/package/%40gebit/stax-cli/?lang=original
项目主页：https://github.com/GEBITSolutions/stax/tree/main/cli#readme
源码仓库：https://github.com/GEBITSolutions/stax

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：91.1 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：4 个
- 首次发布：2026-10-20T14:28:41.173Z
- 最新版本发布：2026-11-08T22:18:09.720Z
- 近 30 天下载量：2150（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

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

## 安装

```sh
npm install @gebit/stax-cli
```

也可以使用：`pnpm add @gebit/stax-cli`、`yarn add @gebit/stax-cli`、`bun add @gebit/stax-cli`

## README

# 语法 CLI

脚手架,扩展并验证了税堆框架的项目. 软件包 [`@gebit/stax-cli`](https://www.npmjs.com/package/@gebit/stax-cli)二进制 `stax`。需要节点24或稍后.

```bash
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` 编辑器在同一版本完成的图解链接 |

```bash
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 和状态部署值;参见 [部署配置](https://npmcn.com/package/%40gebit/docs/docs/configuration.md)。 。 。 .

生成的呼叫器包括 `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/`数字 :

```bash
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`](https://npmcn.com/package/%40gebit/schema/deploy-config.schema.json) 并且违反管道执行的规则.

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

```bash
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` `runtime` | `source_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>`。 。 。 .

## 发展

```bash
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`](https://npmcn.com/package/%40gebit/.github/workflows/release.yml) 跑在每一个推 `main` 并构成 `a-wf-release-*` 相位工作流程 :

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

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

## 常见问题

### @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 和提交记录判断。

