# @alxia/create 中文文档

规范地址：https://npmcn.com/package/%40alxia/create/

版本：0\.5\.14
npm 元数据更新时间：2026-11-01T16:21:57.882Z
中文译文更新时间：2026-11-06T15:28:22.708Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40alxia/create
原文对照：https://npmcn.com/package/%40alxia/create/?lang=original
源码仓库：https://github.com/softistx/alxia

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

- 包体积（解压后）：328 kB，110 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-10-04T02:39:22.822Z
- 最新版本发布：2026-11-01T16:21:57.686Z
- 近 30 天下载量：2907（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

启动 alxia 应用程序 : `bun create @alxia` 写一个最小的 API, 一个 spec- first , 一个 GraphQL 1, 或者反应路由器的官方模板, 由 alxia 服务

## 安装

```sh
npm install @alxia/create
```

也可以使用：`pnpm add @alxia/create`、`yarn add @alxia/create`、`bun add @alxia/create`

## README

# @ alxia/ 创建

开始一个 [阿尔克夏](https://github.com/softistx/alxia) 在一个命令中应用: a 尝试 alxia 的最小一个, 一个使用 Zod 写 OpenAPI spec first, a GraphQL API 先写出计划, 或反应路由器的官方模板 由艾克夏负责.

```sh
bun create @alxia my-app
```

`bun create @alxia` 运行此软件包的文件夹, 如 `bun create <name>` 运行 `create-<name>` 财务报告和审定财务报表 `bun create @scope` 运行 `@scope/create`它要求 未给出的, 写入项目, 安装并打印下一个 步骤 :

```sh
cd my-app
bun dev
```

它需要1.4.2号或以后, 而它写的项目正在运行.

## 模板

```sh
bun create @alxia my-app --template minimal      # the template to try alxia with
bun create @alxia my-api --template api
bun create @alxia my-graph --template graphql
bun create @alxia my-site --template react-router
```

`minimal` 首先是:一个文件,一个依赖,一个测试,以及 `bun dev` 30秒后回复.

| 模板 | 它写的是什么 |
| --- | --- |
| `minimal` | 最小的 alxia 应用 : `src/index.ts` 出口 `app = alxia().get("/", …)` 并倾听 `PORT` 只有输入文件, `src/index.spec.ts` 给它打电话 `app.request()`· ; `bun dev` (单位:千美元)`NODE_ENV=development bun --hot`, (中文(简体) ), `build`, (中文(简体) ), `start`, (中文(简体) ), `typecheck`严格 `tsconfig.json`,Biome和 `verify` (单位:千美元)`check:ci`, (中文(简体) ), `typecheck`,则 `test`页:1 `Dockerfile` 运行中 `oven/bun:1-alpine`, (中文(简体) ), `.dockerignore`, (中文(简体) ), `.gitignore`, (中文(简体) ), `.vscode/` 和读取。 一个依赖, `@alxia/core`: 没有 OpenAPI, 没有代码生成, 没有校验器, 没有 env 文件 |
| `api` | a 一个 `@alxia/core` 应用与 Zod, OpenAPI 光谱 : `openapi.yaml` 声明 `GET /todos`, (中文(简体) ), `POST /todos` 财务报告和审定财务报表 `GET /todos/{id}`· ; `bun run generate` 写入 `src/generated/` 从它与 [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen) (单位:千美元)`openapi-codegen.config.ts`),承诺,所以安装或建造时没有产生任何物; `src/env.ts` 读取 `PORT`, (中文(简体) ), `API_KEY`, (中文(简体) ), `API_DOCS` 和可选 `TRUSTED_PROXIES` (CIDR范围,增加 `trustProxy({ trusted, untrusted: "refuse" })` 返回基数时: `ctx.ip` 来自信任的代理 `X-Forwarded-For`,一个来自任何其它拒绝连接,健康探测器未触及的转发信头) `defineEnv` 从 [`@alxia/env`](https://www.npmjs.com/package/@alxia/env), (中文(简体) ), `API_KEY` 秘密默认为 `dev-key` 下级 `NODE_ENV` `development` 财务报告和审定财务报表 `test` 单独一人,其他任何地方都需要; `src/context.ts` 守住航道的基地, `alxia({ errors: "problem" })` 所以Alxia自己的错误是 RFC 9457问题,因为 `openapi.yaml` 申报,并登记 `@alxia/core`是因为 `Register`· ; `src/routes/todos.ts`时 `defineRoutes()`,读取上下文,但不导入应用程序,并将每个操作与 `route(operation, …middlewares, handler)`,作为 `route(operations.createTodo, requireKey, handler)`时 `requireKey`时 `defineMiddleware`,在没有API密钥的情况下回答401,操作的策略验证请求并检查处理者的答复; `src/app.ts` 挂载 `health()` (单位:千美元)`GET /health`, (中文(简体) ), `GET /ready`, (中文(简体) ), `apiDocs` 从 `@alxia/openapi` (在 `/docs`从 `openapi.yaml` 输入到捆绑中; 正在开发中, 否则 `API_DOCS=true`和基地上的路线;a `bun test` 斯凯, `src/proxy.spec.ts`,在后面建立基地 `TRUSTED_PROXIES` 和电话 `app.fetch` 与同伴, `src/env.spec.ts`,检查一个畸形 `TRUSTED_PROXIES` 停止应用,一个 `bun test` 通过输入调用应用程序的光谱 [`@nxgt/openapi-httpyz`](https://www.npmjs.com/package/@nxgt/openapi-httpyz) 客户端在生成时 `operations.ts`页:1 `fetch` 状态 `app.fetch` (正在处理中,没有服务器;答复的状态缩小),保留一个 `app.request()` 检验和断言 `matchesSpec` 从 [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi):每个行动都有它的路线,以及 `strict: true` 在光谱以外的路线上也失败; `bun dev` (单位:千美元)`NODE_ENV=development`变化重新开始, `typecheck`, (中文(简体) ), `build`严格 `tsconfig.json`生物群落`biome.json`, (中文(简体) ), `lint`, (中文(简体) ), `format`, (中文(简体) ), `check`, (中文(简体) ), `check:ci`, (中文(简体) ), `verify`,从 `generate --check`页:1 `Dockerfile` 运行中 `oven/bun:1-alpine`, (中文(简体) ), `.dockerignore`, (中文(简体) ), `.gitignore`, (中文(简体) ), `.env.example`, (中文(简体) ), `.vscode/` 和读取. `@alxia/openapi` 属属; `@nxgt/httpyz`, (中文(简体) ), `@nxgt/openapi-httpyz` 财务报告和审定财务报表 `@nxgt/openapi-codegen` 是依赖关系 |
| `graphql` | a 图QL API 与 [图QL 瑜伽](https://the-guild.dev/graphql/yoga-server) 结束 [`@alxia/graphql`](https://www.npmjs.com/package/@alxia/graphql),首先计划: `schema.graphql` 合同( 日期)`Query`, (中文(简体) ), `Mutation`, (中文(简体) ), `Subscription`(三); `bun run generate` 写入 `src/generated/resolvers.ts` 从它与 [GraphQL 代码生成器](https://the-guild.dev/graphql/codegen) (单位:千美元)`codegen.ts`),执业,打字 `Resolvers` 应用的上下文; `src/context.ts` 拥有基地 `viewerOf`,中间软件读取 `Authorization: Bearer <token>` 因此,每个解析器读取一个键 `viewer`· ; `src/loaders.ts`, (中文(简体) ), `createLoaders()`,则 [数据记录器](https://github.com/graphql/dataloader)一项请求的 s , 由 `context` 选项 `graphql()` 内 `src/app.ts` 这样 `Note.author` 将笔记列表的作者装入一个批次(`findUsers`而不是每次打一通电话; `src/resolvers.ts`· ; `src/schema.ts` 财务报告和审定财务报表 `src/app.ts` 正在安装 `health()` 财务报告和审定财务报表 `graphql(app, { schema, context })`,只用克图QL; `src/env.ts` (单位:千美元)`PORT` 选项 `TRUSTED_PROXIES`,作为 `api`与 `defineEnv`· ; `src/store.ts`在记忆中,与酒吧/潜水员 `noteAdded` 订阅(服务器发送事件);a `bun test` 发送到 `/graphql` 结束 `app.request()`, (中文(简体) ), `src/proxy.spec.ts`, 后面的基数 `TRUSTED_PROXIES`,以及 `src/env.spec.ts`一个畸形的人拒绝了, `Dockerfile`,Biome和 `.vscode/` 作为 `api`, (中文(简体) ), `verify` 从开始 `generate --check`,则a `.env.example`。 。 。 . `@alxia/graphql`, (中文(简体) ), `@alxia/env`, (中文(简体) ), `dataloader`, (中文(简体) ), `graphql` 财务报告和审定财务报表 `graphql-yoga` 是依赖关系; 代码生成器是一个 dev依赖关系 |
| `react-router` | 反应路由器的官方模板, 如 `create-react-router` 写入、 装入此包并复制, 并带有 [`@alxia/react-router`](https://www.npmjs.com/package/@alxia/react-router) 校对:Soup `alxia()` 内 `vite.config.ts`插件 :, `dev` 下级 `NODE_ENV=development`, (中文(简体) ), `start` 运行 `NODE_ENV=production bun build/server/index.js`页:1 `bunfig.toml` 启动 Bun, a 上的路由器 CLI `Dockerfile` 运行中 `oven/bun:1-alpine` 代替路由器的节点之一,Biome作为 `api` 项目有它,脚手架 由它格式化一次。 没有服务器文件:默认文件为网页服务; `bunx alxia-react-router reveal` 写出来自定义 |

心脏 `api` 工程、其中间软件和绑定到 运行 `openapi.yaml` (整个文件, 以及如何添加一个操作, 处于 [指南](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#the-api-template):

```ts
// src/context.ts, in part: the base, registered
export const base = alxia().decorate({ todos });

declare module "@alxia/core" {
  interface Register {
    context: typeof base;
  }
}

// src/routes/todos.ts, in part: no import of the app
const requireKey = defineMiddleware(({ request, reply }, next) =>
  request.headers.get("x-api-key") === env.API_KEY
    ? next()
    : reply(401, { error: "unauthorized" as const }),
);

export const todoRoutes = defineRoutes()
  .route(operations.createTodo, requireKey, ({ body, todos, reply }) => {
    const todo = { id: todos.length + 1, title: body.title, done: false };
    todos.push(todo);
    return reply.created(todo);
  });

// src/app.ts
export const app = base.plugin(todoRoutes);
```

`operations.createTodo` 实值 `POST /todos` 作为 `openapi.yaml` 声明: 尸体在操作员面前验证 操作员读取它打字 (a) 处理者的答复与小组的答复核对; `requireKey`是因为 401是它自己的,按原样发送. 要更改 API,请编辑 `openapi.yaml` 运行 `bun run generate`; 绝不编辑 `src/generated/`。 。 。 .

这个 `graphql` 项目的心脏,一个计程器和一个解析器读取键入 `viewer` (通过,有订阅和如何添加一个字段) [指南](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#the-graphql-template):

```ts
// schema.graphql, in part
//   type Mutation { addNote(text: String!): Note! }

// src/context.ts, in part: a middleware, then the resolvers' context
const viewerOf = defineMiddleware(({ request }, next) => {
  const token = request.headers.get("authorization")?.match(/^Bearer (.+)$/i)?.[1];
  const id = token === undefined ? undefined : db.tokens.get(token);
  return next({ viewer: (id === undefined ? undefined : db.users.get(id)) ?? null });
});
export const base = alxia().decorate({ env, db }).use(viewerOf);
export type Context = GraphQLContext<typeof base, { loaders: Loaders }>;

// src/resolvers.ts, in part: `Resolvers` is generated from the schema
export const resolvers: Resolvers = {
  Mutation: {
    addNote: (_, { text }, { viewer, db }) => {
      if (viewer === null) {
        throw new GraphQLError("Sign in to add a note", {
          extensions: { code: "UNAUTHENTICATED" },
        });
      }
      // …
    },
  },
  Note: {
    // The notes of one query load their authors in one batch (N+1 otherwise).
    author: (note, _, { loaders }) => loaders.user.load(note.authorId),
  },
};
```

要更改 API,请编辑 `schema.graphql` 运行 `bun run generate`从来没有 编辑 `src/generated/`。 。 。 .

## 缩写和格式

每艘项目船 [生物体](https://biomejs.dev/),设置方式相同:a `biome.json` 拥有Biome推荐的规则、空间和 双引号,导入排序,构建输出(和 `.react-router/` 或者说 `src/generated/`(一) 如果项目有它们,则跳过; `@biomejs/biome` 正如Biome所问的,完全被钉住 `.vscode/` 建议其扩展,格式化为保存。 一个新项目 通过 `bun run check:ci` 没有发现.

| 脚本 | 运行 |
| --- | --- |
| `bun run check` | `biome check --write`: 涂料、格式和分类导入, 修正其可能的内容 |
| `bun run lint` | `biome lint` |
| `bun run format` | `biome format --write` |
| `bun run check:ci` | `biome ci`: CI 运行,只读 |
| `bun run verify` | `minimal`数字 : `check:ci`, (中文(简体) ), `typecheck`,则 `test`· ; `api` 财务报告和审定财务报表 `graphql`数字 : `generate --check`然后这些; `react-router`数字 : `check:ci`, (中文(简体) ), `typecheck`,则 `build` |
| `bun run generate` | `api`数字 : `nxgt-openapi generate`, (中文(简体) ), `src/generated/` 从 `openapi.yaml`· ; `graphql`数字 : `graphql-codegen`, (中文(简体) ), `src/generated/resolvers.ts` 从 `schema.graphql`; 与 `--check`,不写,文件呆滞时退出 1 |

```sh
cd my-api
bun run verify
```

`check:ci` 没有 `ci`,从 `bun ci` bun的冷冻锁文件安装, 名称的脚本 `ci` 将不替换。 这个 [指南](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#lint-and-format) 有设置和原因.

## 夹克

每个项目都以成像为基础: `oven/bun:1`运行 `oven/bun:1-alpine` 作为非根 `bun` 用户, a 图像 大约 130 MB。 每个 `Dockerfile` 建筑在自己的舞台上, 图像仅保留建筑输出, 没有 `node_modules`数字 :

-   `minimal`数字 : `bun run build` 捆绑 `src/index.ts` 输入 `dist/index.js`; 数据 图像持有 `dist/` 运行 `bun --no-install dist/index.js`。 。 。 .
-   `api`数字 : `bun run build` 捆绑 `src/server.ts` 及其依存关系 `dist/server.js`, (中文(简体) ), `src/generated/` 包括作为承诺,因此 构建生成无;图像控件 `dist/` 运行 `bun --no-install dist/server.js`。 。 。 .
-   `graphql`数字 : `bun run build` 捆绑 `src/server.ts`,其附属关系和 `schema.graphql` (输入为正文) `dist/server.js`, (中文(简体) ), `src/generated/` 包括承诺; 图像保存 `dist/` 运行 `bun --no-install dist/server.js`,关闭 GraphiQL(`NODE_ENV=production`,所以alxia的dev开关关闭了).
-   `react-router`数字 : `bun run build`,每个依赖 `build/server/index.js` 以 `@alxia/react-router`插件; 图像 持有 `build/` 运行 `bun --no-install build/server/index.js`。 。 。 .

```sh
cd my-api
docker build -t my-api .
docker run -p 3000:3000 -e API_KEY=change-me my-api   # API_KEY is required: the app does not start without it
```

`minimal` 财务报告和审定财务报表 `graphql` 运行相同的方式,没有 `-e`数字 : `docker run -p 3000:3000 my-app`。 。 。 .

```sh
cd my-site
docker build -t my-site .
docker run -p 3000:3000 my-site
```

提交 `bun.lock` 那个 `bun install` 写入: 图像从中安装 与 `--frozen-lockfile`编辑 [指南](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#docker) 有阶段 [排除出问题](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error-cannot-find-package--from-appdistserverjs) 对于一个不能捆绑的依赖,以及对于一个 [仅用于 glibc 的本地添加符](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl), (中文(简体) ), 不载入高山.

## 选项

| 选项 |  |
| --- | --- |
| `[dir]` | 在哪里写入工程:一个已空出或尚未存在的目录。 未给出时询问 |
| `--template <name>`, (中文(简体) ), `-t` | `minimal`, (中文(简体) ), `api`, (中文(简体) ), `graphql` 或者说 `react-router`问到没有给出, `minimal` 默认 |
| `--no-install` | 写入文件, 跳过 `bun install` |
| `--help`, (中文(简体) ), `-h` | 用途 |

都这样 `dir` 财务报告和审定财务报表 `--template`它不问什么,所以它运行 在剧本 (原始内容存档于2018-03-26). 或CI.

## 版本数

-   **alxia 的软件包** —— 说 `@alxia/core`, (中文(简体) ), `@alxia/env` (单位:千美元)`api`, (中文(简体) ), `graphql`, (中文(简体) ), `@alxia/openapi` (单位:千美元)`api`, (中文(简体) ), `@alxia/graphql` (单位:千美元)`graphql`和 `@alxia/react-router` (单位:千美元)`react-router`——移至登记处最新版本 在此范围内释放 `@alxia/create` 发表于: `^0.3.1` 写入 `^0.3.4` 一次出0.3.4,从不 `^0.4.0`之后 虽然登记册尚未为该版本服务,但最新版本 同一未成年人被写作(`^0.3.0`一旦到达,则需要0.3.1, 输出是这么说的. `bunx @alxia/create@<version>` 选择旧的套装.
-   **其他的都一样** — Zod, TypeScript, Vite, React, React 路由器, GraphQL, 尾风——当项目完成时被移动到登记册的最新版本 写入, 在范围 alxia 包接受: TypeScript 内 `^6.0.3 || ^7.0.0`内部 `^7.0.0 || ^8.0.0`,反应路由器及其 软件包内部 `^8.0.0`,在 `^4.2.0`, (中文(简体) ), `graphql` 在内部 `^16.11.0 || ^17.0.0` 财务报告和审定财务报表 `graphql-yoga` 在内部 `^5.16.0`; 无 alxia 包件 约束到npm的 `latest`阿尔克萨射程外的一个新主力是 左出,输出说.
-   **生物体** 写得准确,写得准确: 模板的次要, `2.5.15` 写作 `2.5.16` 但从不 `2.6.0`,其新的 规则未检查模板.
-   **密码生成器** 被固定在模版上 版本,从未移动到更新的补丁 : `@nxgt/openapi-codegen` (单位:千美元)`api`, (中文(简体) ), `0.11.0`)和 GraphQL 代码生成器 `@graphql-codegen/cli`, (中文(简体) ), `typescript` 财务报告和审定财务报表 `typescript-resolvers` (单位:千美元)`graphql`) (中文(简体) ). `bun run verify` 运行 `generate --check` 对所犯 `src/generated/`,该释放 以不同方式写入文件会在新工程中失败 .

登记处就是那个 `BUN_CONFIG_REGISTRY` 或者说 `npm_config_registry` 名称,其他npmjs.org;不回答时,模板是自己的 版本保留,并带有警告.

## 其他软件包管理器

```sh
bunx @alxia/create my-app --template minimal
npm create @alxia my-app -- --template minimal
```

垃圾箱运行在 Bun (`#!/usr/bin/env bun`以跑者开始,和 它所写的工程 `bun install`。 。 。 .

## API 密码

| 导出 |  |
| --- | --- |
| `create-alxia` | 弹匣 `bun create @alxia`, (中文(简体) ), `bunx @alxia/create` 财务报告和审定财务报表 `npm create @alxia` 运行。 包输出无模块 |

## 文档

-   [指南](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md): 每个模板文件按文件排列, 向操作添加 `api` 工程和一个字段 `graphql` 一个,什么 `react-router` 模板添加到 React 路由器、 Biome 的设置中 `Dockerfile`,如何选择版本,并在 CI 中运行.
-   [解决问题](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md):每条消息,命令印出,如何处理.
-   [路线图](https://github.com/softistx/alxia/blob/develop/packages/create/docs/roadmap.md):即将到来的,以及没有计划的.
-   [食谱](https://github.com/softistx/alxia/blob/develop/docs/recipes/README.md)数字 : [五分钟后开始](https://github.com/softistx/alxia/blob/develop/docs/start.md), (中文(简体) ), [光谱第一 CRUD API](https://github.com/softistx/alxia/blob/develop/docs/recipes/spec-first-crud.md), (中文(简体) ), [图形QL API](https://github.com/softistx/alxia/blob/develop/docs/recipes/graphql-api.md), (中文(简体) ), [与 Docker 一起部署](https://github.com/softistx/alxia/blob/develop/docs/recipes/deploying.md)。 。 。 .

## 常见问题

### @alxia/create 是什么？

启动 alxia 应用程序 : bun create @alxia 写一个最小的 API, 一个 spec- first , 一个 GraphQL 1, 或者反应路由器的官方模板, 由 alxia 服务

### 如何安装 @alxia/create？

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

### @alxia/create 支持 TypeScript 吗？

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

### @alxia/create 支持 ESM 还是 CommonJS？

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

### @alxia/create 可以商用吗？

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

### @alxia/create 的下载量有多少？

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

### @alxia/create 还在维护吗？

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