# @architect/sandbox 中文文档

规范地址：https://npmcn.com/package/%40architect/sandbox/

版本：9\.0\.0
npm 元数据更新时间：2026-03-03T19:04:07.221Z
中文译文更新时间：2026-11-06T14:30:19.026Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：196 kB，89 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：19 个
- 首次发布：2019-05-30T06:15:29.330Z
- 最新版本发布：2025-11-27T23:35:16.245Z
- 近 30 天下载量：15776（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：331（近 12 个月 3 个）

## 中文简介

建筑师 Dev 服务器: 在本地和下线运行完整的建筑师项目

## 安装

```sh
npm install @architect/sandbox
```

也可以使用：`pnpm add @architect/sandbox`、`yarn add @architect/sandbox`、`bun add @architect/sandbox`

## README

[![](https://assets.arc.codes/architect-logo-500b@2x.png)](https://www.npmjs.com/package/@architect/sandbox)

## [`@architect/sandbox`](https://www.npmjs.com/package/@architect/sandbox)

> 建筑师本地开发环境:在一个内幕沙盒中运行全建筑师项目并离线

[![GitHub CI status](https://github.com/architect/sandbox/workflows/Node%20CI/badge.svg)](https://github.com/architect/sandbox/actions?query=workflow%3A%22Node+CI%22)

## 安装

```
npm i @architect/sandbox
```

* * *

## 国 际

### 启动沙盒

```
npx sandbox
```

或者如果从里面运行 Sandbox `@architect/architect`数字 :

```
npx arc sandbox
```

### CLI 选项

-   `-p`, (中文(简体) ), `--port` - 手工指定 HTTP 端口
    -   默认为 `3333`
-   `-h`, (中文(简体) ), `--host` - 指定供Sandbox监听的主机接口
    -   默认为 `0.0.0.0` (机器上所有可用的接口)
    -   只接受本地连接, 请指定 `localhost`
-   `-v`, (中文(简体) ), `--verbose` - 启用动词记录
-   `-d`, (中文(简体) ), `--debug` - 启用调试记录
-   `-q`, (中文(简体) ), `--quiet` - 禁用(大多数)记录
-   `--disable-delete-vendor` - 启动时禁用删除 Lambda 供应商 dirs
-   `--disable-symlinks` - 禁用并联 `src/shared` 输入所有函数并使用文件复制

### 环境变量

-   `ARC_API_TYPE` - 设置 API 网关 API 类型
    -   可以成为其中之一 `http` (别名为 `httpv2`, (中文(简体) ), `httpv1`, (中文(简体) ), `rest`
    -   默认为 `http`
-   `ARC_ENV` - 说吧 `testing|staging|production`
    -   默认为 `testing`
-   `ARC_HOST` - 指定供Sandbox监听的主机接口
    -   默认为 `0.0.0.0` (机器上所有可用的接口)
    -   只接受本地连接, 请指定 `localhost`
-   `ARC_LOCAL`\- 如与下列情况一并存在和使用: `ARC_ENV=staging|production`,模拟直播 `staging` 或者说 `production` 环境
    -   用你们的 [当地偏好 `@env`](https://npmcn.com/package/%40architect/configuration/local-preferences#%40env) 适当阶段的环境变量
    -   连接 Sandbox 直播 AWS 事件和 DynamoDB 基础设施
    -   需要有效的 AWS 证书,其配置名称与您定义的相同 [项目表](https://npmcn.com/package/%40architect/project-manifest/aws#profile)
-   指定端口 :
    -   `ARC_PORT` - 手工指定 HTTP 端口
        -   默认为 `3333`
    -   `ARC_EVENTS_PORT`\- 手动指定事件总线端口
        -   默认为 `4444`
    -   `ARC_TABLES_PORT`\- 手动指定本地DynamoDB端口
        -   默认为 `5555`
    -   `ARC_INTERNAL_PORT`\- 手工指定内部Sandbox + AWS 服务端口
        -   默认为 `2222`
-   `ARC_DB_EXTERNAL` - (Boolean)使用外部的DynamoDB工具(例如: [AWS 无 SQL 工作台](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html)(中文(简体) )
-   `ARC_QUIET` - 如果存在,则禁用(大多数)记录

* * *

## API 密码

Sandbox被设计成融入您的应用程序的测试套房. 在大多数情况下你只需要利用 `sandbox.start()` 财务报告和审定财务报表 `sandbox.end()`然而,个人Sandbox服务也可以单独开始和停止。 ([见下文](https://npmcn.com/package/%40architect/sandbox/#readme-individual-sandbox-services). ) (中文(简体) )

可传递包含下列参数的选项对象:

-   `apigateway` - 说吧 **字符串** - 指定 API 网关 API 类型
    -   默认为 `http`
    -   可以成为其中之一 `http` (别名为 `httpv2`, (中文(简体) ), `httpv1`, (中文(简体) ), `rest`
-   `cwd` - 说吧 **字符串** - 指定一个工作目录(用于在测试模拟器瞄准沙盒)
-   `deleteVendor` - 说吧 **布尔** - 启动时删除Lambda供应商 dirs
    -   默认为 `true`
-   `env` - 说吧 **对象** - 自动测试中Lambda引用的环境变量
    -   字符串值覆盖同一名称的内侧 vars 通过 `.env` 或者说 `prefs.arc` 文件
    -   `undefined` 值删除同名设置的任何内存 vars `.env` 或者说 `prefs.arc` 文件
-   `port` - 说吧 **字符串或数字** - 指定 HTTP 端口
    -   默认为 `3333`
-   `quiet` - 说吧 **布尔** - 禁用(大多数)记录
-   `runStartupCommands` - 说吧 **布尔** - 禁用 `@sandbox-start` 命令
    -   默认为 `true`
-   `runtimeCheck` - 说吧 **字符串** - 检查运行时版本不匹配
    -   如果设置为 `warn` Sandbox 会警告 Stdout 中的错配
    -   如果设置为 `error` (针对试验环境建议) 沙盒启动失败
    -   不默认运行
-   `symlink` - 说吧 **布尔** - 从每个Lambda的属地内部(例如:. `src/http/get-index/node_modules/@architect/shared` → `src/shared`(中文(简体) )
    -   默认为 `true`
    -   `false` 复制共享代码输入每个 Lambda, 这会导致启动速度和依赖补水速度慢得多
-   `watcher` - 说吧 **布尔** - 禁用 Sandbox 文件监视器(和相关 Sandbox 文件监视器插件 API)
    -   默认为 `true`

* * *

### 沙盒

> 启动并关闭 Sandbox; 除非您有具体的服务需求, 我们一般建议大多数人使用此接口进行测试

### `sandbox.start(options[, callback]) → [Promise]`

启动 Sandbox ; 首先检查是否有可消费的端口, 打印一个横幅, 加载建筑师和用户地环境变量, 水合物应用程序依赖性, 并开始各种 Sandbox 服务( 包括 `@events`, (中文(简体) ), `@queues`, (中文(简体) ), `@tables`, (中文(简体) ), `@indexes`, (中文(简体) ), `@http`, (中文(简体) ), `@static` 财务报告和审定财务报表 `@ws`) (中文(简体) ).

调用 `callback` 一旦一切准备就绪,或返回 `promise` 若为 `callback` 是恶作剧.

### `sandbox.end([callback]) → [Promise]`

关闭任何开始 `sandbox.start()`。启动 `callback` 关闭或返回 `promise` 若为 `callback` 是恶作剧.

* * *

## 示例

### 磁带

```javascript
let sandbox = require('@architect/sandbox')
let test = require('tape')

test('Start the Sandbox', async t => {
  t.plan(1)
  let result = await sandbox.start()
  t.equal(result, 'Sandbox successfully started')
})

test('Tests go here', t => {
  // Make use of various Sandbox resources in your tests...
})

test('Shut down the Sandbox', async t => {
  t.plan(1)
  let result = await sandbox.end()
  t.equal(result, 'Sandbox successfully shut down')
})
```

### 欢乐

```javascript
let sandbox = require('@architect/sandbox')

beforeAll(async () => {
  let result = await sandbox.start()
  expect(result).toBe('Sandbox successfully started')
})

afterAll(async () => {
  let result = await sandbox.end()
  expect(result).toBe('Sandbox successfully shut down')
})

test('Tests go here', () => {
  // Make use of various Sandbox resources in your tests...
})
```

## 发展

### 所需资源

这个存储器的测试需要您拥有 `deno` 运行时间安装在您的本地机器上 。 安装 `deno` 访问: [https://deno.land/#安装](https://deno.land/#installation)

### 运行测试

要在沙盒上工作, 首先确定您已经安装了依赖性 :

```
npm install
```

进行所有测试,包括天线:

```
npm test
```

跑来跑来跑去

```
npm run lint
```

仅进行单元测试(位于 `test/unit`:

```
npm run test:unit
```

要获取基于单位测试执行的代码覆盖报告 :

```
npm run coverage
```

仅进行综合测试(位于“测试/综合”):

```
npm run test:integration
```

要让测试运行 额外的噪音类似,添加 `NOISY_TESTS=true` 环境 var

## 常见问题

### @architect/sandbox 是什么？

建筑师 Dev 服务器: 在本地和下线运行完整的建筑师项目

### 如何安装 @architect/sandbox？

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

### @architect/sandbox 支持 TypeScript 吗？

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

### @architect/sandbox 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @architect/sandbox 需要什么版本的 Node\.js？

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

### @architect/sandbox 可以商用吗？

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

### @architect/sandbox 的下载量有多少？

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

### @architect/sandbox 还在维护吗？

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