# @aurelienbbn/conformance-alchemy 中文文档

规范地址：https://npmcn.com/package/%40aurelienbbn/conformance-alchemy/

版本：0\.1\.1
npm 元数据更新时间：2026-10-14T14:04:34.374Z
中文译文更新时间：2026-11-08T03:20:38.791Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aurelienbbn/conformance-alchemy
原文对照：https://npmcn.com/package/%40aurelienbbn/conformance-alchemy/?lang=original
项目主页：https://github.com/aurelienbobenrieth/harness/tree/main/packages/conformance-alchemy#readme
源码仓库：https://github.com/aurelienbobenrieth/harness

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

- 包体积（解压后）：189 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.19\.0 \|\| ^24\.11\.0
- 运行依赖：2 个
- peer 依赖：vitest \>=4\.1\.11 \<6\.0\.0
- 首次发布：2026-09-28T13:39:00.955Z
- 最新版本发布：2026-10-14T14:04:33.900Z
- 近 30 天下载量：1915（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Alchemy v2 项目的结构相容性检查:状态,CI,预览,平分. 包装为Vitest套房.

## 安装

```sh
npm install @aurelienbbn/conformance-alchemy
```

也可以使用：`pnpm add @aurelienbbn/conformance-alchemy`、`yarn add @aurelienbbn/conformance-alchemy`、`bun add @aurelienbbn/conformance-alchemy`

## README

# @aurelienbn/ 遵义- 意识

[![npm](https://img.shields.io/npm/v/@aurelienbbn/conformance-alchemy)](https://www.npmjs.com/package/@aurelienbbn/conformance-alchemy) [![downloads](https://img.shields.io/npm/dm/@aurelienbbn/conformance-alchemy)](https://www.npmjs.com/package/@aurelienbbn/conformance-alchemy) [![CI](https://github.com/aurelienbobenrieth/harness/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/aurelienbobenrieth/harness/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@aurelienbbn/conformance-alchemy)](https://github.com/aurelienbobenrieth/harness/blob/main/packages/conformance-alchemy/LICENSE) [![node](https://img.shields.io/node/v/@aurelienbbn/conformance-alchemy)](https://github.com/aurelienbobenrieth/harness/blob/main/packages/conformance-alchemy/package.json)

**4次检查可以捕捉Alchemy v2的设置 一次部署精细,然后丢失你的基础设施: 状态承诺 git, CI 部署在本地状态, PR预览无人破坏,以及浮动的β版本.**

```text
 alchemy.run.ts ────┐
 .gitignore + git ──┼─▶ alchemyChecks (4) ─▶ report { passed | incomplete | failed }   Vitest or plain function
 .github/workflows ─┤
 package.json(s) ───┘
```

> \[尖叫声\] **筛选出候选人 `alchemy@2.0.0-beta.79`一个已知的消费者.** Alchemy的CLI和州API仍然在β之间移动; `alchemy plan` 保持权威 对于部署会做什么.

## 一个文件,四个测试

```ts
// conformance.test.ts
import { alchemyConformance } from "@aurelienbbn/conformance-alchemy/vitest";

alchemyConformance({ root: process.cwd() });
```

**错误失败; 警告打印 。 缺少证据(没有工作流程目录,运行时从目录集运行的软件包脚本)显示为跳过测试,永远不会通过.** `vitest` 是可选对等点; 节点 `^22.19.0 || ^24.11.0`。 。 。 .

```ts
import { runAlchemyConformanceReport } from "@aurelienbbn/conformance-alchemy";

const report = await runAlchemyConformanceReport({ root: process.cwd() }); // { status, checks[], findings[] }
```

| 评价 | 原因 | 维特 | 报告情况 |
| --- | --- | --- | --- |
| `evaluated` | 运行到补全;仍然可以保存错误 | ✅/❌ | 通过/失败 |
| `skipped` | 列入清单 `skipChecks` | ⏭️ | 不完整 |
| `unsupported` | 没有工作流程, 它无法解决的脚本或目录, 未识别 `state:` | ⏭️ | 不完整 |
| `failed` | 没有堆栈文件, 没有 `alchemy` 依赖, 无效的 YAML/ JSON/ TypeScript, 掷出 | ❌ | 失败 |

调查结果 `check`, (中文(简体) ), `severity`, (中文(简体) ), `message`, (中文(简体) ), `path`页:1 `docs` URL,还有 `evaluation` 当证据不见了.

## 检查

| 检查 | 失败的时间 |
| --- | --- |
| `alchemy-pinned-exact` | 工作空间 `package.json` (或它指的pnpm目录) `alchemy` 预 1.0 或预释线上的区域 |
| `alchemy-state-gitignored` | 持有堆栈文件的目录没有忽略强制规则 `.alchemy/`,或 `.alchemy/` 文件已跟踪 |
| `ci-uses-remote-state` | 工作流程步骤运行 `alchemy deploy` 或者说 `destroy` 对一个堆 `state:` 实值 `localState()` 或者说 `inMemoryState()` |
| `preview-cleanup` | 工作流程部署a `pr-*` 没有 `alchemy destroy` 页:1 `pr-*` 开始 `pull_request` `closed`; 破坏可以击中 prod |

每一次检查渔获量及其限度

### 炼金术

```jsonc
"alchemy": "^2.0.0-beta.79"  // ❌ the next lockfile refresh can pull a breaking beta
"alchemy": "catalog:"        // ❌ when pnpm-workspace.yaml has `alchemy: ~2.0.0-beta.79`
"alchemy": "2.0.0-beta.79"   // ✅ also through `catalog:` / `catalog:<name>` resolving to it
```

贝塔斯断裂时没有大起落: `2.0.0-beta.78` 使每个非交互式 `alchemy deploy` 在CLI制造器的包子相撞下[炼金术# 1689](https://github.com/alchemy-run/alchemy/issues/1689)) (中文(简体) ). 读取 `dependencies`, (中文(简体) ), `devDependencies`,以及 `optionalDependencies` 和每个成员 `pnpm-workspace.yaml` `packages` 或者说 `package.json` `workspaces`。其下限为稳定 1.0+释放的区域保持缄默. `workspace:`, (中文(简体) ), `file:`, (中文(简体) ), `link:`,并且没有支持。 A 类 `catalog:` 没有匹配条目 QQ 失败。 锁文件没有被读取 .

### 炼金术 - 状态 - 被忽略

```gitignore
# apps/api/alchemy.run.ts
dist/            # ❌ apps/api/.alchemy/ is not ignored
.alchemy/        # ✅ root or apps/api/.gitignore; `.alchemy`, `.alchemy/*`, `**/.alchemy` work too
```

`localState()` 写入 `.alchemy/state/<stack>/<stage>/*.json`,将资源产出列入CLI的工作目录。 探测器是 `<stack dir>/.alchemy/state/`在一棵工作树里 它问 `git check-ignore --no-index`,所以每个规则 git 应用计数,然后拒绝匹配从 `.git/info/exclude` 或全局排除文件:队友不分享. `git ls-files` 也未能说明已经作出承诺。 没有git(不是工作树,没有) `git` 二进制读取 `.gitignore` 来自 `root` 下至带有 git 模式规则的堆栈目录; 上面的文件 `root` 未读。 A 类 `--config` 堆栈从另一个目录运行 `.alchemy/` 此处,此检查没有遵循.

### ci-uses-远程状态

```ts
state: localState(),                                          // ❌ with any CI `alchemy deploy`/`destroy` of this stack
state: Cloudflare.state(),                                    // ✅ also AWS.state(), postgresState()
state: process.env.CI ? Cloudflare.state() : localState(),    // ⚠️ warns: confirm CI takes the remote branch
```

一个CI跑者抛弃物 `.alchemy/state` 与工作:下一个部署从空地状态开始,与活的资源相撞,一个破坏计划一无所获并泄露出来. 查找 `alchemy <command>` 数字 `run:` 台阶:赤出, `npx`编号 :`bunx`编号 :`pnpx`, (中文(简体) ), `pnpm [exec|dlx]`, (中文(简体) ), `yarn [dlx]`, (中文(简体) ), `bun [x|run]`, (中文(简体) ), `npm exec`,与 `cd <dir> &&`, (中文(简体) ), `working-directory` 财务报告和审定财务报表 `defaults.run`软件包脚本`pnpm ship`, (中文(简体) ), `npm run ship`, (中文(简体) ), `bun run ship`, (中文(简体) ), `yarn ship`)从最近处读取 `package.json` 并紧随其后的两层深处,附上转递的论据(a/cn.9/wg.iii/wp.61,附件)`bun run deploy --stage pr-1`; npm 仅在之后 `--`) (中文(简体) ). 软件包选择解析 `-C`编号 :`--dir`编号 :`--prefix`编号 :`--cwd`, (中文(简体) ), `-w`编号 :`--workspace`, (中文(简体) ), `-ws`, (中文(简体) ), `-r`, (中文(简体) ), `yarn workspace <name>`,以及 `--filter`编号 :`-F` 名字或路标. **运行一个脚本的其他任何信息都会被报告为不支持,永远不会被删除**: 一个目录 `${{ matrix.* }}` 或者说 `$VAR`, (中文(简体) ), `--filter` 图表选择器( e)`pkg...`, (中文(简体) ), `!pkg`, (中文(简体) ), `{dir}`, (中文(简体) ), `yarn workspaces foreach`,第三个嵌入脚本,无法读取 `package.json`。 。 。 . `deploy --dry-run` 计为计划。 堆栈文件是 `<cwd>/<--config or positional or alchemy.run.ts>`,用牛语解析: `state:` 内 `Stack(...)`, (中文(简体) ), `Alchemy.Stack(...)`,或 `Stack.make(...)`,存储构造器仅通过其 `alchemy`, (中文(简体) ), `alchemy/State`, (中文(简体) ), `alchemy/Cloudflare`, (中文(简体) ), `alchemy/AWS` 进口,顶级 `const`s 跟踪。 一个没有Alchemy命令通过的工作流程:没有任何损失.

### 预览清理

```yaml
- run: alchemy deploy --stage pr-${{ github.event.number }} # ❌ alone: every closed PR leaves resources running
# ✅ plus, in a workflow on `pull_request: types: [closed]`:
- run: alchemy destroy --stage pr-${{ github.event.number }}
- run: alchemy destroy --stage prod # ❌ never destroy production from CI
```

舞台是 `--stage`,则 `ALCHEMY_STAGE`,与 `${{ env.X }}`, (中文(简体) ), `$X`, (中文(简体) ), `${X}` 从工作流程、工作和步骤中替换 `env` (两次,所以工作值读取工作流程) `env` 决议。 包含 `pr-` 是预览,涵盖共享 `STAGE: ${{ ... format('pr-{0}', ...) || 'prod' }}` alchemy CI 指南的模式。 毁灭必须针对同堆栈文件,除非任何一方的目录是动态的. 舞台上的毁灭 `prod` 编号 : `production` 失败; 一个表达方式包含任意一个字的失败, 除非在同一任务上的一个步骤, 直至毁灭, 运行 `exit 1` 并命名制作(指南的拒绝检查)或 `pr-` (允许列表,如 `case "$STAGE" in pr-*) ;; *) exit 1;; esac`; 警卫的状况没有评估. a 中未解决的脚本 `closed` 工作流程将缺失的清理变成QQ不支持,因为脚本可能是毁灭. 一个分支字面上的名字 `prod` 到达 `github.ref_name` 可见此字形检查.

## 选项

| 选项 | 默认 | 用于 |
| --- | --- | --- |
| `root` | 需要:寄存器根 | 全部 |
| `skipChecks` | `[]` (未知的 ids 抛出) | 全部 |
| `stackFiles` | `["**/alchemy.run.ts"]`,无节点 模块 | `alchemy-state-gitignored` |
| `workflowsDir` | `.github/workflows` | `ci-uses-remote-state`, (中文(简体) ), `preview-cleanup` |

未检查, 属于别处 : 部署是否成功 `alchemy plan`)),CI中提供商证书`alchemy provider check-env`, (中文(简体) ), `CI=true` 页:1 `Cloudflare.state()`,通过 `$GITHUB_ENV`,可重复使用的工作流程和复合动作,GitHub Actions以外的CI系统.

## 来源

独立执行炼金术 [国库](https://alchemy.run/state-store/), (中文(简体) ), [中情局](https://alchemy.run/environments/ci/),以及 [阶段](https://alchemy.run/environments/stages/) 指南和指南 [部署](https://alchemy.run/cli/deploy/) 编号 : [销毁](https://alchemy.run/cli/destroy/) 参考文献,2026-09-25查阅 `alchemy@2.0.0-beta.79` 来源(`State/LocalState.ts`, (中文(简体) ), `Stack.ts`, (中文(简体) ), `Cli/commands/flags.ts`页:1 [炼金术# 1689](https://github.com/alchemy-run/alchemy/issues/1689)。源带 greppable `@attribution` 标签.

## 登记的合同库存

从软件包导出 `pnpm catalog`. 规则特定选项和限制在上文和源测试中都有描述.

| 规则/检查 | 触发或审查范围 |
| --- | --- |
| `alchemy-pinned-exact` | 每个工作空间包. json将炼金术钉入了精确的版本(pnpm目录已解析出)而Alchemy是前1.0或前放出. |
| `alchemy-state-gitignored` | 每个持有堆栈文件的目录都会忽略所承诺的.gitignore中的.alchemy/. |
| `ci-uses-remote-state` | 每个CI炼金术都部署或摧毁了目标堆放有远程国家商店的堆放,而不是本地国家(. |
| `preview-cleanup` | 每个 CI 部署到 pr- \* 阶段, 都有一个匹配的 炼金术 在拉 请求关闭, 任何破坏都无法瞄准 prod. |

### 信用概念

-   [https://alchemy.run/environments/ci/ 互联网档案馆的存檔,存档日期2013-12-22](https://alchemy.run/environments/ci/) (激励;独立执行)
-   [https://alchemy.run/ 环境/舞台/](https://alchemy.run/environments/stages/) (激励;独立执行)
-   [https://alchemy.run/state-store/ 页面存档备份,存于互联网档案馆](https://alchemy.run/state-store/) (激励;独立执行)
-   [https://github.com/alchemy-run/alchemy/issues/1689 (中文(简体) )](https://github.com/alchemy-run/alchemy/issues/1689) (激励;独立执行)

## 常见问题

### @aurelienbbn/conformance-alchemy 是什么？

Alchemy v2 项目的结构相容性检查:状态,CI,预览,平分\. 包装为Vitest套房\.

### 如何安装 @aurelienbbn/conformance-alchemy？

在项目目录运行 npm install @aurelienbbn/conformance-alchemy，或使用 pnpm add / yarn add / bun add。

### @aurelienbbn/conformance-alchemy 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aurelienbbn/conformance-alchemy 支持 ESM 还是 CommonJS？

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

### @aurelienbbn/conformance-alchemy 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.19\.0 \|\| ^24\.11\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aurelienbbn/conformance-alchemy 可以商用吗？

@aurelienbbn/conformance-alchemy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aurelienbbn/conformance-alchemy 的下载量有多少？

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

### @aurelienbbn/conformance-alchemy 还在维护吗？

最新版本 0\.1\.1 发布于 2026/10/14（24 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/09/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。