# @codepress/codepress-engine 中文文档

规范地址：https://npmcn.com/package/%40codepress/codepress-engine/

版本：0\.11\.3
npm 元数据更新时间：2026-11-05T03:49:15.327Z
中文译文更新时间：2026-11-10T07:29:38.047Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：17.8 MB，47 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，@babel/core ^7\.0\.0
- 首次发布：2025-10-14T03:55:40.009Z
- 最新版本发布：2026-11-05T03:49:15.167Z
- 近 30 天下载量：37874（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：231（近 12 个月 220 个）

## 中文简介

代码新闻引擎 - Babel和SWC插件

## 安装

```sh
npm install @codepress/codepress-engine
```

也可以使用：`pnpm add @codepress/codepress-engine`、`yarn add @codepress/codepress-engine`、`bun add @codepress/codepress-engine`

## README

## 代码新闻引擎

> **被贬,可选.** 代码Press 平原云预览的视觉编辑工作 没有构建插件的 dev 服务器: 预览运行时间从它们的 DOM 中定位元素 位置、文本和框架提示以及编辑由承诺执行您的代理程序应用 树枝。 本地设备预览目前仍然需要插件 。 不需要安装这个 用于云预览的软件包。 如果您的应用程序已经使用过, 一切不变: 编辑器仍然 读取 `codepress-data-fp` 属性并用作元素所在的第一个提示 活着 插件没有规划新功能 .

用于代码Press视觉编辑器的TypeScript动力仪器. 软件包将一个 Babel 插件, SWC 插件, 开发服务器, 和 CLI 所以 React 或 Next.js 项目可以向编辑器显示文件级别上下文 .

* * *

## 所需资源

-   节点.js **18.17.0或更新** (快活V5+诊断通道支持)
-   npm 8+(或任何相容的软件包管理器)
-   主机上可用的 Git( 仓库和分支检测)

> 在节点16下进行自动测试,当运行时间缺乏所需的API时,跳过Fastify特定断言. 对于生产用途,我们强烈建议18+节点.

* * *

## 安装

```bash
npm install @codepress/codepress-engine
```

### 下一个.js 使用量

```js
// next.config.mjs
import { createSWCPlugin } from "@codepress/codepress-engine/swc";
import CodePressWebpackPlugin from "@codepress/codepress-engine/webpack-plugin";

const nextConfig = {
  // SWC plugin for code transformation (existing)
  experimental: {
    swcPlugins: [createSWCPlugin()],
  },

  // Webpack plugin for production module mapping (new)
  webpack: (config, { isServer, dev }) => {
    config.plugins.push(new CodePressWebpackPlugin({ isServer, dev }));
    return config;
  },
};

export default nextConfig;
```

### 如何运作

插件 :

1.  自动跳过服务器构建( N)`isServer: true`)和dev建筑(`dev: true`(中文(简体) )
2.  制作客户端的 Webpack 编译过程中的运行
3.  构建映射 : `{ 33: "react", 92: "react-dom", ... }`
4.  喷出 `window.__CP_MODULE_MAP__` 输入主捆绑
5.  启用 O(1) 模块分辨率而不是扫描所有模块

### 套装大小影响

-   典型应用(1 000个模块):+3-4KB gzipped
-   大应用程序 (3 000个模块): +8- 10KB gziped

### 何时使用

-   **需求**: 生产建设中您需要高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温/高温
-   **可选**: 开发(已命名模块ID)
-   **备选案文**设置 `moduleIds: 'named'` 在 webpack 配置中( 更大的捆绑, 暴露文件结构)

注: 当使用无害环境管理时(`next.config.mjs`),由于CJS interop,更喜欢上面所命名的导入. 对于普通JS配置, 您可以使用 :

```js
// next.config.cjs
const { createSWCPlugin } = require("@codepress/codepress-engine/swc");
```

SWC 插件自动检测您的寄存器和分支 `git` 和常见的CI Env vars. WASM 选择基于您的 Next.js / `@swc/core` 版本; 手动覆盖请参看下面的 WASM 导出 .

可选选项 `createSWCPlugin` (都是可选的;省略使用自动检测) :

| 选项 | 类型 | 默认 | 目的 |
| --- | --- | --- | --- |
| `repo_name` | 字符串 | 自动从 `git remote` | 强制寄存器 id in `owner/repo` 表单 |
| `branch_name` | 字符串 | 从掩码/ 自动检测`git` | 强制分支名称 |

* * *

## Babel 插件的使用

```js
// babel.config.mjs
export default {
  plugins: ["@codepress/codepress-engine"],
};
```

联合来文X的每个要素都得到一个 `codepress-data-fp` 属性,其值编码了相对路径和起始/结束行号。 在第一个根容器上(`html`, (中文(简体) ), `body`,或 `div`),插件还注入了寄存器和分支元数据.

Babel 插件的可选选项( 全部是可选的; 省略使用自动检测) :

| 选项 | 类型 | 默认 | 目的 |
| --- | --- | --- | --- |
| `repo_name` | 字符串 | 自动从 `git remote` | 强制寄存器 id in `owner/repo` 表单 |
| `branch_name` | 字符串 | 从掩码/ 自动检测`git` | 强制分支名称 |

包暴露的出入口 :

| 导出 | 说明 |
| --- | --- |
| `@codepress/codepress-engine/babel` | 编译的 Babel 插件( CommonJS) |
| `@codepress/codepress-engine/swc` | SWC 插件厂和 WASM 助手 |
| `@codepress/codepress-engine/webpack-plugin` | 生产模块地图的 Webpack 插件 |
| `@codepress/codepress-engine/server` | 快速化开发服务器厂 |
| `@codepress/codepress-engine/cli` | 用于 `codepress` 二进制 |

* * *

## 项目布局

| 路径 | 细节 |
| --- | --- |
| `src/` | Babel 插件、 CLI、 dev 服务器和 utils 的脚本类型源 |
| `dist/` | 编译的 JavaScript + 声明文件(`npm run build`(中文(简体) ) |
| `babel/` | 再导出已编译 Babel 插件的轻量级代理 |
| `swc/` | Next.js 14, 15.5+在15.x, 和16.3 SWC主机ABIs的版本WASM 二进制, 加插件条目 |
| `tests/`, (中文(简体) ), `test/` | 覆盖 Babel、SWC 和服务器助手的套房 |

* * *

## 构建测试工作流程( T)

```bash
# Install dependencies
npm install

# Compile TypeScript into dist/
npm run build

# Run Jest (ts-jest powered)
npm test
```

由于 Babel 和 CLI 的切入点来自 `dist/`。当运行时间不支持诊断通道时, Jest 自动进行类型检查并跳过快速化整合测试.

* * *

## 地方发展

将本地的 CodePress 服务器与您的应用程序一起运行到磁盘上的可视化编辑代码( 没有 GitHub 承诺):

```bash
# npm
npx codepress && npm start

# pnpm
pnpm dlx codepress && pnpm start

# yarn
yarn dlx codepress && yarn start
```

有用命令 :

```bash
# Show available commands
npx codepress help

# Launch the server explicitly on port 4321
npx codepress server

# Scaffold .env entries required by the server
npx codepress setup
```

环境变量(来自 `.env` 现时:

| 变量 | 默认 | 目的 |
| --- | --- | --- |
| `CODEPRESS_DEV_PORT` | `4321` | 快捷收听端口 |
| `CODEPRESS_BACKEND_HOST` | `localhost` | 代码Press后端主机名 |
| `CODEPRESS_BACKEND_PORT` | `8007` | 后端 REST 端口 |
| `CODEPRESS_API_TOKEN` | _未设定_ | 用于认证代理呼叫的 API 令牌 |

服务器执行 git-aware 写入并用寄存器元数据丰富回复. 它会写入您本地文件系统的更改, 并且不用于生产构建 .

* * *

## 将一个已建网站发布为 CodePress app

`codepress publish` 以 CodePress App 的形式发布您已经构建的目录( 它不运行您的构建) :

```bash
codepress publish ./dist --org <org> --app <app> [--publish] [--message "..."] [--no-wait]
```

-   `--org` 财务报告和审定财务报表 `--app` 取UUID或一发子弹.
-   `--publish` 同时发布部署的文件作为App的公开网站.
-   `--message` 编号 : `-m` 设置承诺消息.
-   `--no-wait` 完成后打印部署 ID , 不等待任务退出 0 。 如果部署已经结束,但没有成功,例如,在长时间上传期间过期,则报告1号出口.

命令对目录进行行走,将每个文件都散开. 然后,它开始部署 一份清单: `{path, sha256, size}`,并仅上传组织尚未持有的文件,一次8个,直接存储。 最后,它完成了部署,并印出每个阶段及其进展,直到部署结束.

**退出代码.** 命令在部署成功时退出 0 。 它在部署失败、 中断或过期时退出 1 , 例如打印错误类别和信件 `branch_moved: ...`。当API拒绝请求时,它也会退出 1,例如打印打出的理由 `deployment_in_progress` 或者说 `deployment_unsupported_delivery_mode`第二个组织通过抽取请求审查生成的应用程序;这些组织继续从代理会议中发表.

**复说s言.** 再次运行同一个目录是便宜的. 组织已经持有的文件没有上传 。 一份相同的清单附在仍在开放的部署上。 在成功后不久,它又将部署作为 `deduped` 没有新的工作。 如果一个上传的 URL 过期, 命令会重命名一次, 并重试该文件一次 .

**发表什么.** 该目录是走的方式 经纪人的 `commit_app` 显示构建输出 。 每个普通文件都包含在内,点文件也包含在内 `index.html` 必须是根。 一个同义链接或其他特殊文件被拒绝,因此将该资产复制为正则文件. 服务器执行App限制:512个文件,每个文件20个米B,总共50个米B.

状态命令 :

```bash
codepress deployments <app> --org <org> [--limit N]   # recent deployments, newest first
codepress deployment <deployment-id> --org <org> --app <app>
```

| 变量 | 默认 | 目的 |
| --- | --- | --- |
| `CODEPRESS_TOKEN` | _所需经费_ | 全权证书,以 `Authorization: Bearer` |
| `CODEPRESS_API_URL` | `https://api.codepress.dev` | API 来源( 有无) `/v1`(中文(简体) ) |
| `CODEPRESS_DEPLOY_POLL_INTERVAL_MS` | `2000` | 指挥员多久投票一次 |

### 获得一个标志

部署 API 接受 CodePress 登录令牌, 同一会话令牌 网络应用和 CodePress 终端使用, 或平台 API 密钥(见下文 CI / 长寿密钥) 。 您可以以以下两种方式获得登录符:

-   **从代码Press终端.** 已签名终端保存为 `webAuthToken` 内 `~/.codepress-terminal/settings.json`。 。 。 .
-   **从一个电子邮件和密码账户.** 打电话 `POST /v1/auth/jwt/login` 与 `{"email", "password"}` 并带 `access_token` 从回应.

登录标志持续14天. 当它接近到期时,API返回一个已刷新的在 `X-New-Token` 头曰. 命令在运行的其余时间使用刷新符号并打印一个提醒, 但是它不能更新您的环境, 所以替换 `CODEPRESS_TOKEN` 在旧的过期之前.

**CI/长寿密钥.** 命令从不检查符;它只作为"熊"证书发送. 对于 CI,使用 CodePress 平台 API 键(`cpk_...`,在设置 > 集成 > 平台 MCP 下创建 `apps:write` 范围(开始并最后确定)和 `apps:read` 范围(状况和清单)。 一个403名称 范围 键缺失。 弹簧检查只接受一个登录符号, 所以有密钥命令要求组织 和 App UUID : 通过 UUID 到 `--org` 财务报告和审定财务报表 `--app`。 。 。 .

### 从 `commit-code` + 键 `publish` 脚本

将每个文件读入一个文件的脚本 `POST /v1/app-code/organizations/{org}/apps/{app}/commit-code` 请求然后呼叫 `POST /v1/websites/{app}/publish` 在一个大的站点上进行几分钟的开放请求。 将这两通电话替换为:

```bash
CODEPRESS_TOKEN=... codepress publish ./dist --org <org> --app <app> --publish
```

`--publish` 从单独的网站发布呼叫中接手,所以你不再先阅读世代和文物SHA. 任何内容都无法内传:每个文件都会被上传一次,一个不变的文件再也不会上传. 您为旧任务请求提出的超时请求可以取消, 因为服务器承诺时没有请求保持开放 。 旧路线在迁移时继续工作.

* * *

## SWC 套件导出和 WASM 选择

| 导出 | 目标 |
| --- | --- |
| `./swc` | `./dist/swc/index.js` |
| `./swc/wasm` | `./swc/codepress_engine.v42.wasm` |
| `./swc/wasm-v42` | `./swc/codepress_engine.v42.wasm` |
| `./swc/wasm-turbopack` | `./swc/codepress_engine.turbopack.wasm` |
| `./swc/wasm-v73` | `./swc/codepress_engine.v73.wasm` |
| `./swc/wasm-turbopack-v73` | `./swc/codepress_engine.turbopack-v73.wasm` |
| `./swc/wasm-v26` | `./swc/codepress_engine.v26.wasm` |
| `./swc/wasm-v0_82_87` | `./swc/codepress_engine.v0_82_87.wasm` |

帮助者根据检测到的 Next.js / 自动选择正确的 WASM 二进制 `@swc/core` 版本。 Next.js 15.5和后15.x的释放使用swc core 42的出口; Next.js 16.3.x使用swc core 73的出口,每个家族都有专用的涡轮包装工艺品. 未支持的 Next.js 16 未成年人以可操作相容性错误失败, 而不是装入 ABI 匹配的 二进制 。 覆盖检测方式 `CODEPRESS_SWC_WASM=<package specifier>` 或者说 `CODEPRESS_SWC_ABI_BAND=<v42|turbopack|v73|turbopack-v73|v26|v0_82_87>` 在对照主机编译器验证选定文物后.

* * *

## 特征比较

| 能力 | Babel 插件 | SWC 插件 |
| --- | --- | --- |
| Git 意识属性 | ✅ | ✅ |
| 编码路径安全 | XOR + 基数64 | XOR + 基数64 |
| 线路编号跟踪 | 开始 - 结束范围 | (可选) |
| 业绩 | 基线 | **20-70x 更快 20-70x 更快 20-70x** |
| 输出介质 | 字符串属性 | `[wasmSpecifier, config]` 数组 |

* * *

## 其他参考资料

-   `INSTALL.md` - 连接本地软件包和发布指南
-   `MODULE_MAP_INTEGRATION.md` - webpack 插件集成和故障排除的详细指南
-   `scripts/build-swc.mjs` 重建 WASM 二进制( 需要 Rust 工具链)
-   `tests/` - 在验证插件时嘲笑 git、 获取和文件 IO 的实例

* * *

## 捐款

欢迎公关 请确保:

1.  `npm run build`
2.  `npm test`

提交前均为绿色。 如果由于在节点 < 18上运行而跳过快速集成测试,则在PR描述中提及.

根据麻省理工学院的许可发布 CodePress 引擎(参见 `LICENSE`) (中文(简体) ).

## 常见问题

### @codepress/codepress-engine 是什么？

代码新闻引擎 - Babel和SWC插件

### 如何安装 @codepress/codepress-engine？

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

### @codepress/codepress-engine 支持 TypeScript 吗？

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

### @codepress/codepress-engine 支持 ESM 还是 CommonJS？

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

### @codepress/codepress-engine 可以商用吗？

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

### @codepress/codepress-engine 的下载量有多少？

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

### @codepress/codepress-engine 还在维护吗？

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