# @architect/utils 中文文档

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

版本：6\.0\.3
npm 元数据更新时间：2026-03-03T19:04:08.608Z
中文译文更新时间：2026-11-06T14:29:24.189Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：141 kB，51 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2019-05-29T17:38:37.278Z
- 最新版本发布：2025-12-04T00:04:08.315Z
- 近 30 天下载量：4130979（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：135（近 12 个月 8 个）

## 中文简介

共同公用事业职能

## 安装

```sh
npm install @architect/utils
```

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

## README

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

[@ architect/ utils](https://www.npmjs.com/package/@architect/utils) 用于 [@ architect](https://github.com/architect) 框架生态系统。 它为AWS Lambda开发、CLI操作、基础设施管理、AWS证书验证和静态资产指纹用于无服务器应用提供了必不可少的工具.

## 安装

```
npm i @architect/utils
```

# API 密码

## `utils.banner(params)`

负责打印标准横幅,显示环境信息,包括app名称,AWS区域,配置,版本,以及当前工作目录等.

**参数:**

-   `params` (对象,可选): 下列属性的配置对象 :
    -   `inventory` (目标,要求): 库存对象 `@architect/inventory`
    -   `cwd` (字符串):当前工作目录(默认为 `process.cwd()`(中文(简体) )
    -   `disableBanner` 跳过全部打印横幅
    -   `version` (字符串):要显示的软件包版本字符串(默认为"-")
    -   `quiet` (boolean): 禁用横幅打印

**回返情况:** `undefined`

**示例**

```js
let utils = require('@architect/utils')
let inventory = require('@architect/inventory')

utils.banner({
  inventory,
  version: 'Architect 1.2.3'
})
```

**环境变量:**

-   `ARC_QUIET` - 如果真伪, 则禁用打印
-   `QUIET` - 如果真伪, 则禁用打印
-   `AWS_REGION` - 如果不在库存中配置AWS区域
-   `AWS_PROFILE` - 如果不在库存中配置 AWS 配置文件
-   `AWS_ACCESS_KEY_ID` - 如果设置, 显示“ 通过环境设置” 配置文件

## `utils.chars`

返回终端 UI 打印的适合平台的 CLI 字符 。 为Windows和Unix类系统提供不同的字符集,以确保跨平台的正确显示.

**参数:** 无( 这是对象, 不是函数)

**回返情况:** 以下属性的对象 :

-   `buzz` (字符串): 进步指标字符 (Unix上的'Q',Windows上的'~')
-   `start` (字符串):开始指标字符 ("Q"在Unix上,"0"在Windows上)
-   `done` (字符串):完成指标字符 (Unix上的'',Windows上的''')
-   `warn` (字符串):警告指示字符 ("在Unix上","!"在Windows上)
-   `err` (字符串):出错指示字符 ("×"在Unix上,"×"在Windows上)

**示例**

```js
let utils = require('@architect/utils')
console.log(`${utils.chars.done} Task completed successfully`)
console.log(`${utils.chars.warn} Warning message`)
```

**有关公用事业:** 用于 `utils.banner()` 财务报告和审定财务报表 `utils.updater()` 用于一致的 CLI 字符显示

## `utils.checkCreds(params, callback)`

通过尝试初始化一个 AWS 客户端来进行基本的 AWS 证书验证. 用于核查在进行AWS操作前是否有有效的AWS证书.

**参数:**

-   `params` (目标,要求): 下列属性的配置对象 :
    -   `inventory` (目标,要求): 库存对象 `@architect/inventory`
-   `callback` (功能,可选):节点.js风格的回调功能 `(err) => {}`

**回返情况:** 保证不提供回调,否则 `undefined`

**示例**

```js
let utils = require('@architect/utils')
let inventory = require('@architect/inventory')

// With callback
utils.checkCreds({ inventory }, (err) => {
  if (err) console.log('Invalid AWS credentials')
  else console.log('AWS credentials are valid')
})

// With promise
try {
  await utils.checkCreds({ inventory })
  console.log('AWS credentials are valid')
} catch (err) {
  console.log('Invalid AWS credentials')
}
```

## `utils.deepFrozenCopy(obj)`

创建一个对象的深层复制并递归地冻结所有嵌入对象,使整个结构不可变. 大约比基于JSON的深度复制快了2x,同时也提供了不可磨损性.

**参数:**

-   `obj` 复制和冻结对象

**回返情况:** 输入对象的深冻副本

**示例**

```js
let utils = require('@architect/utils')

let original = { 
  config: { debug: true },
  items: [1, 2, { nested: 'value' }]
}

let frozenCopy = utils.deepFrozenCopy(original)
// frozenCopy is completely immutable
// frozenCopy.config.debug = false // This would throw an error
```

## `utils.fingerprint(params, callback)`

创建一个 `static.json` 显示文件,将原始文件名映射到带有内容散列的指纹版本.

**参数:**

-   `params` (目标,要求): 下列属性的配置对象 :
    -   `inventory` (目标,要求): 库存对象 `@architect/inventory`
    -   `fingerprint` 启用指纹( 默认为 `inventory.inv.static.fingerprint`(中文(简体) )
    -   `ignore` (阵列):要忽略的文件模式阵列(默认为 `inventory.inv.static.ignore`(中文(简体) )
    -   `update` (功能):进度报告的更新功能
-   `callback` (功能,需要):节点.js风格回调功能 `(err, manifest) => {}`

**回返情况:** `undefined`

**示例**

```js
let utils = require('@architect/utils')
let inventory = require('@architect/inventory')

utils.fingerprint({ 
  inventory,
  fingerprint: true 
}, (err, manifest) => {
  if (err) throw err
  console.log('Generated fingerprint manifest:', manifest)
  // manifest = { 'app.js': 'app-a1b2c3d4e5.js', ... }
})
```

**环境变量:**

-   静态资产设置使用库存配置

**有关公用事业:** 用途 `utils.pathToUnix()` 内部用于跨平台路径处理

## `utils.getLambdaName(fn)`

通过应用符合Lambda命名要求(最多64个字符,字母,数字,连字符,并仅下划线)的字符替换来将一个架构师路由路径转换为有效的AWS Lambda函数名.

**参数:**

-   `fn` (字符串):架构器路由(例如"/api/用户/:id")

**回返情况:** 有效的 AWS Lambda 函数名( 字符串)

**示例**

```js
let utils = require('@architect/utils')

utils.getLambdaName('/') // Returns: '-index'
utils.getLambdaName('/api/users') // Returns: '-api-users'
utils.getLambdaName('/api/users/:id') // Returns: '-api-users-000id'
utils.getLambdaName('/api/v1.0/users') // Returns: '-api-v1_0-users'
```

**字符转换规则 :**

-   `/` (根)变成 `-index`
-   `-` 变成 `_`
-   `.` 变成 `_`
-   `/` 变成 `-`
-   `\` 变成 `-`
-   `:` 变成 `000`
-   `*` 变成 `catchall`

**有关公用事业:** 与 `utils.toLogicalID()` 用于 CloudFormation 资源命名

## `utils.pathToUnix(pathString)`

将任何文件路径转换为 Unix 风格格式,并将前向斜线作为分隔符。 对跨平台相容性至关重要,尤其是在运行于后鞭为默认路径分隔的Windows上时.

**参数:**

-   `pathString` (字符串):要转换的文件路径

**回返情况:** 带有向前斜线的Unix 风格路径字符串

**示例**

```js
let utils = require('@architect/utils')

utils.pathToUnix('C:\\Users\\dev\\project') // Returns: 'C:/Users/dev/project'
utils.pathToUnix('/unix/path/already') // Returns: '/unix/path/already'
utils.pathToUnix('relative\\windows\\path') // Returns: 'relative/windows/path'
```

**有关公用事业:** 内部使用 `utils.fingerprint()` 用于跨平台静态资产处理

## `utils.toLogicalID(str)`

将短写字符串转换成适合CloudFormation逻辑ID的PascalCase格式。 处理特例并确保输出符合CloudFormation命名要求.

**参数:**

-   `str` (字符串):转换为 PascalCase 的字符串

**回返情况:** 适合 CloudFormation 逻辑标识的 PascalCase 字符串

**示例**

```js
let utils = require('@architect/utils')

utils.toLogicalID('my-api-function') // Returns: 'MyApiFunction'
utils.toLogicalID('user_profile') // Returns: 'UserProfile'
utils.toLogicalID('get') // Returns: 'GetIndex' (special case)
utils.toLogicalID('api-v1.0') // Returns: 'ApiV10'
```

**有关公用事业:** 补充 `utils.getLambdaName()` aWS 资源命名公约

## `utils.updater(name, params)`

创建标准化进度指标并使用多种输出方法进行记录。 自动尊重建筑师的全球印刷状况和环境变量,以获得一致的CLI经验.

**参数:**

-   `name` (字符串,需要):更新器的标签(如"部署","建设")
-   `params` (对象,可选): 下列属性的配置对象 :
    -   `quiet` (boolean):手动覆盖全局打印状态
    -   `logLevel` (字符串):设置日志级别("正常","动词","调试")

**回返情况:** 采用下列方法更新对象:

-   `status(message, ...details)` - 打印正态更新
-   `start(message)` - 启动动画进度指标(简称: `update`(中文(简体) )
-   `done(message)` - 以更新(别名: `stop`(中文(简体) )
-   `cancel()` - 未更新即取消当前进度指标
-   `err(error)` - 打印出一个错误(别名: `error`, (中文(简体) ), `fail`(中文(简体) )
-   `warn(message)` - 发出警告(别名: `warning`(中文(简体) )
-   `raw(message)` - 在尊重静默模式的同时将消息记录为是
-   `get()` - 返回当前更新器状态
-   `reset()` - 重新设置更新状态(别名: `clear`(中文(简体) )
-   `verbose` - 动词记录方法
-   `debug` - 调试记录方法

**示例**

```js
let utils = require('@architect/utils')

let update = utils.updater('Deploy')
update.start('Deploying application...')
// ... deployment logic ...
update.done('Application deployed successfully')

// With error handling
try {
  // ... some operation ...
} catch (err) {
  update.err(err)
}
```

**环境变量:**

-   `ARC_QUIET` - 如果真伪, 则禁用打印
-   `QUIET` - 如果真伪, 则禁用打印
-   `CI` - 如果属实, 则禁用某些终端进度动画

**有关公用事业:** 用途 `utils.chars` 用于一致的终端字符显示

## 常见问题

### @architect/utils 是什么？

共同公用事业职能

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

在项目目录运行 npm install @architect/utils，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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