# @geastack/compiler 中文文档

规范地址：https://npmcn.com/package/%40geastack/compiler/

版本：1\.0\.49
npm 元数据更新时间：2026-10-29T09:37:25.132Z
中文译文更新时间：2026-11-16T01:26:27.419Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40geastack/compiler
原文对照：https://npmcn.com/package/%40geastack/compiler/?lang=original
项目主页：https://github.com/geastack/compiler#readme
源码仓库：https://github.com/geastack/compiler

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

- 包体积（解压后）：21.8 MB，1506 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：2 个
- peer 依赖：@geastack/apple \>=0\.2\.14，@geastack/geatsc-plugin-gea \>=0\.1\.19，@geastack/geatsc-plugin-apple-native \>=0\.1\.4
- 首次发布：2026-09-20T03:20:42.155Z
- 最新版本发布：2026-10-29T09:37:24.514Z
- 近 30 天下载量：4029（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

Geastack TypeScript-to-C++编译器:一个语义性脊椎,没有源形权威,没有打入静态打字值的拳击.

## 安装

```sh
npm install @geastack/compiler
```

也可以使用：`pnpm add @geastack/compiler`、`yarn add @geastack/compiler`、`bun add @geastack/compiler`

## README

# 宝石

geatsc将 TypeScript 提前编译为 C++. 输出包含无 JavaScript引擎或解释器. C++ 工具链构建为本地 目标二进制:ESP32或RP2350固件,一个macOS,iOS,Linux或Windows app, Xbox 游戏,或服务器可执行文件.

输入是普通的类型脚本程序,由类型脚本检查 编译器. Geatsc 使用这些类型来选择本地 C++ 表示: 类 成为结构,数字成为本地数字类型,并输入数组、地图和 记录成为打入的容器。 这是让相同的类型脚本运行在一个 微控制器,并让编译的服务器使用一小部分内存 在节点下需要同样的代码.

## 在GeaStack的合适之处

geatsc 是编辑器 [GeaStack 软件](https://github.com/geastack),框架 用于在 TypeScript 和 JSX 中编写应用程序,并在嵌入式上本地运行 板子、桌面、移动和控制台。 另一个寄存器插入它:

-   [`core`](https://github.com/geastack/core) - Gea框架(应用API, 反应、渲染引擎、主机服务)和 `geatsc-plugin-gea`,则 教Geatsc关于Gea组件和JSX的插件.
-   [`cli`](https://github.com/geastack/cli) - 那个 `gea` 命令. `gea build` 运行 vite, 和核心 `build-gea-vite-geatsc.mjs` 将模块图手动到 `geatsc compile-module-graph`。然后,目标的工具链构建 生成 C++.
-   [`targets`](https://github.com/geastack/targets), (中文(简体) ), [`apple`](https://github.com/geastack/apple), (中文(简体) ), [`linux`](https://github.com/geastack/linux), (中文(简体) ), [`windows`](https://github.com/geastack/windows) ——平台项目 编译和链接生成的 C++. `apple` 并运入 geatsc 插件 苹果SDK捆绑.
-   Xbox——Xbox目标不是开源;它是商业上的. 联系人 [联系人@geastack.com](mailto:contact@geastack.com)。 。 。 .
-   [`node-compat`](https://github.com/geastack/node-compat) - 节点Js 用于编译节点服务器的运行时间和 Geatsc 插件(`node:http`, HTTP 框架)改为 本地可执行文件 。 此软件包的依赖性: 运行 `geatsc` 在节点项目内没有输入文件 通过节点相配到 `dist/`。 。 。 .

Gea和Apple插件是同级依赖. 其他插件被装入 `--plugin`; 见 [文件/CLI-PLUGINS.md](https://npmcn.com/package/%40geastack/compiler/docs/CLI-PLUGINS.md)。 。 。 .

[文献/档案](https://npmcn.com/package/%40geastack/compiler/docs/ARCHITECTURE.md) 描述输油管 分层和限制. `CLAUDE.md` 有守则的约定.

## 层层

```
identity/        canonical IDs
semantics/       target-neutral frontend: regions, structural types,
                 operations, edges, coverage
representation/  physical carriers, the sealed plan, fail-closed guards
conversion/      the closed dynamic-conversion capability algebra
preflight/       whole-pipeline capability census and certificate
ir/              typed IR: verified operations and SSA values
targets/cpp/     C++ emission; consumes typed IR only
diagnostics/     authority-component sweep, deterministic ordering
```

`semantics/` 是前端/后端边界。 之后不能导入 `typescript` 或触摸 TypeScript AST.

## 制约因素

1.  **无出源形权威.** 任何决定都不得取决于文件名称, 路径, 源值相冲, `.pos`编号 :`.end`编号 :`getStart()` 以物配主, 源文本、声明或本地拼写、语句布局或生成 C++文本 (中文(简体) ). 身份是检查器符号/声明,密封语义ID, 或版本协议身份.
2.  **没有拳击.** 静态类型的值永远不会得到动态载体. `Representation.dynamic` 只允许四个人 `DynamicReason` 已声明值 `src/representation/model.ts`。 。 。 .
3.  **关闭失败.** 当一个警卫开火时,缺陷是上游. 不要放松一个 警卫,降级 `unresolved`,或替换缺省 事实上. `unresolved` 是花纹底,不是答案.

## 建筑大门

`scripts/architecture.mjs` 检查 `src/**/*.ts` 用于:

-   文件与目录大小限制
-   标题 `src/targets/cpp/`
-   源位置字面比较
-   `typescript` 外部进口 `src/semantics/`
-   源形歧视者
-   未分类 `Authority`编号 :`Admission`编号 :`Proof` 合同
-   类别声明 `src/targets/`
-   `any`

报告一连串的违规事件.

## 诊断

```bash
node dist/cli.js test/fixtures/spread.ts
```

运行整个管道 并打印每个诊断。 无时退出非零 已刻出能力证书 . `--preflight` 打印债务普查 和警犬NDJSON一样.

### 覆盖范围

```bash
node dist/cli.js coverage app/index.ts --plugin ../node-compat/plugin/v2.mjs
```

每个语句打印一行,并带有代码、状态和一行理由, 然后是摘要和每个代码的计数。 箱载载体报告为 连行也. 只有当证书已刻出且没有被拒绝时才退出 0 在减少或排放过程中.

| 代码 | 层 |
| --- | --- |
| `G1xxx` | 类型脚本检查器出错 |
| `G2xxx` | 普查阻断器:编译器缺少的语言原始家族 |
| `G3xxx` | 侵犯代表权 |
| `G4xxx` | 按债务类型分列的失踪/无证明的飞行前债务 |
| `G5xxx` | IR 降低阻断器 |
| `G6xxx` | 按排放类别分列的拒绝排放情况 |
| `G7xxx` | 调用常规(ABI)投影阻断器 |
| `G8xxx` | 箱载载体(`gea::Value`由于原因 |

后面的位数索引固定表格 `src/cli-coverage.ts`,所以重写一个 信件不会更改其代码. `x999` 意思是桌子没有排了.

选项 : `--project`编号 :`--no-project`, (中文(简体) ), `--plugin`, (中文(简体) ), `--plugin-option`, (中文(简体) ), `--json` (数列和汇总为一个对象), `--no-derived` (只有基础), `--no-boxed` (唯辩.

### 承运人

```bash
node scripts/probe-carriers.mjs test/fixtures/language.ts
```

打印每次声明选择的载体和 C++ 拼写,并计数 未解决的和箱式载体.

## 隐藏 C++

```bash
node dist/cli.js compile app/index.ts --out-dir build/generated
```

Gea建管线运行此命令(`build-gea-vite-geatsc.mjs` 通过它 结束 `--geatsc-bin`) (中文(简体) ). 它写给 `--out-dir`数字 :

-   生成的 C++
-   `gea_runtime.h` 财务报告和审定财务报表 `generated_support.hpp`
-   设备旁边安装主机所需的任何文件
-   `geatsc-sources.txt`列表 `.cpp` 要编译的文件
-   `geatsc-header.txt` (只有每个文件的版式),用于预编译的共享标题

| 选项 | 含义 |
| --- | --- |
| `--project <tsconfig.json>` | 编辑下输入的项目 。 默认:最接近的. A 类 `.js` 捆绑没有. |
| `--entry-symbol <name>` | C++ 函数程序启动于 。 默认 `__gea_top_level`,由 `core/gea_app_entry.cpp`。 。 。 . |
| `--dynamic-fallback` | 允许支持动态特性的框式 C++ 运行时间调度 。 没有涉及JavaScript引擎. 见 [文件/DYNAMIC-FALLBACK.md](https://npmcn.com/package/%40geastack/compiler/docs/DYNAMIC-FALLBACK.md)。 。 。 . |
| `--isolate-symbols` | 使每个定义都与这个程序密不可分,因为将多个程序连接到一个二进制中。 无法隔离的程序被拒绝. |
| `--translation-units single | per-file | balanced` | `single` (默认):一个C++文件. `per-file`: 每个源文件一个文件, 外加共享 `<stem>.hpp` 和一个程序单位. `balanced`: 以小单位分组的每个文件。 见 [文件/翻译-联合国](https://npmcn.com/package/%40geastack/compiler/docs/TRANSLATION-UNITS.md)。 。 。 . |
| `--plugin <module>` | 装入编译器插件 。 复有为相. 见 [文件/CLI-PLUGINS.md](https://npmcn.com/package/%40geastack/compiler/docs/CLI-PLUGINS.md)。 。 。 . |
| `--plugin-option <lib.key>=<value>` | 不加修改地传入由前缀命名的库中,例如. `gea.cpp-prelude=...`。 。 。 . |

`compile-module-graph <gea-module-graph.json> --entry <file>` 做同样的 从 Vite 的模块图取而代之的是磁盘上的文件。 应用程序构建使用此功能 形式。 这需要同样的选择.

## npm 脚本

| 脚本 | 目的 |
| --- | --- |
| `architecture` | 运行建筑门 |
| `typecheck` | `tsc -p tsconfig.json --noEmit` |
| `build` | 建筑门,然后编译为 `dist/` |
| `format` | `prettier --write .` |
| `format:check` | `prettier --check .` |
| `check` | 建筑门、打字和格式检查 |

## 许可证

编译器及其链接到生成程序的运行时间为 Apache-2.0 (见 `LICENSE`) (中文(简体) ). 用Geatsc编译的程序是你的;他们的执照 要看他们联系什么 GeaStack 框架和桌面, 移动 网络目标也是Apache-2.0。 嵌入式棋盘支持( E)`targets`, (中文(简体) ), `@geastack/chips`)为GPL-3.0-只;闭源固件需要商用 执照 联系人 [联系人@geastack.com](mailto:contact@geastack.com) 页:1 商业术语.

## 常见问题

### @geastack/compiler 是什么？

Geastack TypeScript-to-C\+\+编译器:一个语义性脊椎,没有源形权威,没有打入静态打字值的拳击\.

### 如何安装 @geastack/compiler？

在项目目录运行 npm install @geastack/compiler，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 geatsc，可以用 npx geatsc 直接运行。

### @geastack/compiler 支持 TypeScript 吗？

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

### @geastack/compiler 支持 ESM 还是 CommonJS？

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

### @geastack/compiler 需要什么版本的 Node\.js？

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

### @geastack/compiler 可以商用吗？

@geastack/compiler 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @geastack/compiler 的下载量有多少？

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

### @geastack/compiler 还在维护吗？

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

