# @canva/app-scripts 中文文档

规范地址：https://npmcn.com/package/%40canva/app-scripts/

版本：1\.2\.0
npm 元数据更新时间：2026-11-09T00:47:17.994Z
中文译文更新时间：2026-11-09T01:27:27.918Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/%40canva/app-scripts
原文对照：https://npmcn.com/package/%40canva/app-scripts/?lang=original

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

- 包体积（解压后）：206 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：28 个
- 首次发布：2026-07-07T22:56:59.292Z
- 最新版本发布：2026-11-09T00:47:17.807Z
- 近 30 天下载量：40879（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

为 Canva Apps 构建脚本和捆绑器配置

## 安装

```sh
npm install @canva/app-scripts
```

也可以使用：`pnpm add @canva/app-scripts`、`yarn add @canva/app-scripts`、`bun add @canva/app-scripts`

## README

# @ canva/ app- crip

为 Canva Apps 构建脚本.

`@canva/app-scripts` 设计用于通过 [坎瓦语CLI](https://www.canva.dev/docs/apps/canva-cli/)数字 : `canva apps start` 财务报告和审定财务报表 `canva apps build` 是您运行和构建应用程序的推荐方式。 更喜欢直接处理包裹? 自己买的 [CLI 命令](https://npmcn.com/package/%40canva/app-scripts/#readme-cli-commands) aPI也为你服务.

## 安装

```bash
npm install -D @canva/app-scripts
```

有个没有用的 Canva App `@canva/app-scripts` 还没有? 你可能有一个 `webpack.config.ts` (单位:千美元) `scripts/start/` 根部有跑动 [移徙指南](https://www.canva.dev/docs/apps/upgrades-and-migrations/app-scripts-migration-guide/) 用来开关.

## 配置

创建可选 `canva-app.config.ts` 文件在您的工程根中以覆盖默认值( e)`.js`, (中文(简体) ), `.mjs`, (中文(简体) ), `.cjs`, (中文(简体) ), `.mts`,以及 `.cts` 也得到支持; 建议类型脚本 :

### 基本配置

```typescript
import { defineConfig } from "@canva/app-scripts";

export default defineConfig({
  entry: "./src/index.tsx",
});
```

### Bundler 选择

默认, `@canva/app-scripts` 用途 **建设** 作为捆绑者。 您可以明确选择捆绑器 :

```typescript
import { defineConfig } from "@canva/app-scripts";

export default defineConfig({
  bundler: "rsbuild", // Default, can be omitted
  entry: "./src/index.tsx",
});
```

**Bundler 支持 :**

-   `rsbuild` - 默认捆绑器
-   `webpack` - 支持的替代办法

### 自定义 Bundler

使用 `config` 函数可自定义基础捆绑器配置。 调用器每捆绑键入,所以 `bundler` 财务报告和审定财务报表 `config` 一起出行,配置类型来源于各捆绑者自己的包(`@rsbuild/core`, (中文(简体) ), `webpack`) (中文(简体) ).

#### Rsbuild( 默认)

```typescript
import { defineConfig } from "@canva/app-scripts";
import type { RsbuildContext } from "@canva/app-scripts";
import type { RsbuildConfig } from "@rsbuild/core";

export default defineConfig({
  config: (rsbuildConfig: RsbuildConfig, { mode }: RsbuildContext) => {
    // Disable source maps for production builds
    if (mode === "production") {
      rsbuildConfig.output = { ...rsbuildConfig.output, sourceMap: false };
    }
    return rsbuildConfig;
  },
});
```

#### 网络软件包

```typescript
import { defineConfig } from "@canva/app-scripts";
import type { WebpackContext } from "@canva/app-scripts";
import type { Configuration } from "webpack";
import path from "path";

export default defineConfig({
  bundler: "webpack",
  config: (webpackConfig: Configuration, { mode }: WebpackContext) => {
    // Add SVG loader - import SVGs as React components
    webpackConfig.module?.rules?.push({
      test: /\.svg$/,
      issuer: /\.[jt]sx?$/,
      use: [
        {
          loader: "@svgr/webpack",
          options: {
            svgoConfig: {
              plugins: [{ name: "removeViewBox", active: false }],
            },
          },
        },
      ],
    });

    // Add path aliases for cleaner imports
    webpackConfig.resolve = {
      ...webpackConfig.resolve,
      alias: {
        ...webpackConfig.resolve?.alias,
        "@components": path.resolve(__dirname, "src/components"),
        "@assets": path.resolve(__dirname, "src/assets"),
      },
    };

    // Enhanced source maps for development
    if (mode === "development") {
      webpackConfig.devtool = "eval-source-map";
    }

    return webpackConfig;
  },
});
```

> **说明:** 自定义加载器喜欢 `@svgr/webpack` 必须单独安装:
> 
> ```bash
> npm install --save-dev @svgr/webpack
> ```

这个 `config` 函数接收 :

-   基础捆绑器配置( E)`RsbuildConfig` 从 `@rsbuild/core`,或 `Configuration` 从 `webpack`(中文(简体) )
-   `context` - 与 `mode` (单位:千美元)`"development"` 或者说 `"production"`(中文(简体) )

### 后端

如果你的应用程序有一个后端,设置 `backend` 与 Dev 服务器一起运行。 它运行在有TypeScript支持的节点下,后端崩溃将dev服务器撕下. 任意后端配置( 偶数) `{}`) 使之得以实现.

```typescript
import { defineConfig } from "@canva/app-scripts";

export default defineConfig({
  entry: "./src/index.tsx",
  backend: true, // runs backend/server.ts
});
```

通过一个对象来覆盖默认值 :

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `entry` | 后端条目,相对于工程根. | `backend/server.ts` |
| `port` | 端口后端监听. 倒计时 `CANVA_BACKEND_PORT`。 。 。 . | `3001` |
| `host` | 后端托管已构建的应用程序呼叫. 倒计时 `CANVA_BACKEND_HOST`。 。 。 . | —— 说 |
| `tunnel` | 通过公共的HTTPS隧道将后端曝光. 被击倒 `--tunnel`。 。 。 . | `false` |

```typescript
export default defineConfig({
  backend: { entry: "./api/main.ts", port: 3100 },
});
```

### Dev 服务器

可选的dev-server选项. CLI 旗帜和环境变量在运行时覆盖这些.

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `port` | 前端德夫服务器端口. 被击倒 `--override-frontend-port`。 。 。 . | `8080` |
| `https` | 在HTTPS前端服务. 被击倒 `--use-https`。 。 。 . | `false` |

```typescript
export default defineConfig({
  devServer: { port: 9000, https: true },
});
```

### 翻译

可选配置 `extract-translations`。 。 。 .

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `outputDir` | 写入已提取信件的目录 . | `dist` |
| `outputFile` | 输出文件名( 没有目录段) . | `messages_en.json` |
| `pattern` | Glob 用于源文件扫描 . | `src/**/*.{ts,tsx}` |

```typescript
export default defineConfig({
  extractTranslations: { outputDir: "i18n", pattern: "app/**/*.tsx" },
});
```

### 环境变量

这些环境变量是支持但可选的. 大多数也可以配置在 `canva-app.config.ts` (被推荐);有些仍只被封入.

| 变量 | 说明 | 需要时 |
| --- | --- | --- |
| `CANVA_FRONTEND_PORT` | Dev服务器端口(默认为8080). 覆盖 `devServer.port`。 。 。 . | 可选的 - 偏好 `devServer.port` |
| `CANVA_BACKEND_PORT` | 后端服务器端口(默认为3001). 覆盖 `backend.port`。 。 。 . | 可选的 - 偏好 `backend.port` |
| `CANVA_BACKEND_HOST` | 后端 URL 已构建的应用程序调用 。 覆盖 `backend.host`。 。 。 . | 可选的 - 偏好 `backend.host` |
| `CANVA_HMR_ENABLED` | 启用热模块替换( E)`true`编号 :`false`) (中文(简体) ). | 可选 |
| `CANVA_APP_ORIGIN` | App 源代码 URL. | 高频 |
| `CANVA_APP_ID` | Canva应用ID. | 运行后端时需要 |
| `NGROK_AUTHTOKEN` | (原始内容存档于2018-07-21). ngrok auuthtoken. | 使用时需要 `--tunnel` |

### 配置优先

当一个选项可以设置在一个以上的地方时,最高优先级获胜: **CLI 旗 > 环境变量 > `canva-app.config.ts` > 包默认值.** 并不是每个频道都有每个选项; CLI 打印 a `Warn:` 当一个阴道var 阴影一个配置值.

### 设计哲学

公众 `defineConfig()` API故意最小化:

-   **`entry`**, (中文(简体) ), **`rootDir`**,以及 **`outputDir`** - 基本应用程序配置
-   **`bundler`** - 选择构建工具(默认创建,也支持网页包)
-   **`devServer`** - 开发服务器选项(端口、HTTPS)
-   **`backend`** - 在dev服务器旁运行后端
-   **`extractTranslations`** - i18n 提取选项
-   **`config`** - 脱逃舱口,供捆绑者定制

每个选项通过CLI旗帜和环境变量在运行时都是压倒性的,因此配置文件持有项目稳定的东西,而引用控制了其余部分.

## CLI 命令

软件包提供了 `canva-app-scripts` CLI带有以下命令. "Canva CLI"的音乐剧 `canva apps start` 财务报告和审定财务报表 `canva apps build` 被推荐的运行方式; 使用 `canva-app-scripts` 如果你不想通过Canva CLI的话.

### `dev`

启动开发服务器 。 服务应用程序从 `src/index.tsx`。 。 。 .

```bash
npx canva-app-scripts dev
```

如果配置了后端( 或 `--backend-entry` ,后端条目在 nodemon 下与 Dev 服务器一起运行,并有 SSL 证书路径传递到它的环境. 一个后端崩溃 撕裂整个dev服务器下来。 见 [后端](https://npmcn.com/package/%40canva/app-scripts/#readme-backend) 用于配置选项.

```bash
npx canva-app-scripts dev --entry ./src/app.tsx
npx canva-app-scripts dev --backend-entry ./backend/server.ts
```

### `build`

构建生产应用. 产出至 `dist/` 默认.

```bash
npx canva-app-scripts build
npx canva-app-scripts build --entry ./src/app.tsx --output-dir ./build
```

### `extract-translations`

从源文件提取 i18n 信件到 `dist/messages_en.json`。 。 。 .

```bash
npx canva-app-scripts extract-translations
npx canva-app-scripts extract-translations --output-dir ./i18n --pattern "src/**/*.{ts,tsx}"
npx canva-app-scripts extract-translations --output-file messages.json
```

### 全球CLI选项

-   `--entry` - 应用程序的条目文件(覆盖) `entry` 从配置; 上 `dev` 财务报告和审定财务报表 `build`(中文(简体) )
-   `--tunnel` -通过公共HTTPS隧道(别名: `--ngrok`(中文(简体) )
-   `--use-https` - 在HTTPS上启动本地开发服务器
-   `--override-frontend-port` - 覆盖前端端口
-   `--backend-entry` - 后端条目脚本路径(覆盖) `backend.entry` 从配置)

## 更改日志

见 `CHANGELOG.md` 文档.

## 捐款

我们正在积极开发这个一揽子计划,但目前不接受第三方的捐款. 如果您想要求修改或添加软件包,请通过 [Canva 开发者社区](https://community.canva.dev/)。 。 。 .

## 许可证

见 `LICENSE.md` 文档.

## 常见问题

### @canva/app-scripts 是什么？

为 Canva Apps 构建脚本和捆绑器配置

### 如何安装 @canva/app-scripts？

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

### @canva/app-scripts 支持 TypeScript 吗？

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

### @canva/app-scripts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @canva/app-scripts 需要什么版本的 Node\.js？

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

### @canva/app-scripts 可以商用吗？

@canva/app-scripts 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @canva/app-scripts 的下载量有多少？

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

### @canva/app-scripts 还在维护吗？

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