# @base44/vite-plugin 中文文档

规范地址：https://npmcn.com/package/%40base44/vite-plugin/

版本：1\.0\.52
npm 元数据更新时间：2026-11-04T12:39:58.447Z
中文译文更新时间：2026-11-07T17:34:04.261Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.2 MB，344 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2025-10-31T05:40:07.240Z
- 最新版本发布：2026-11-04T12:39:58.227Z
- 近 30 天下载量：10281964（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 84 个）

## 中文简介

基于 Base44 应用程序的 Vite 插件

## 安装

```sh
npm install @base44/vite-plugin
```

也可以使用：`pnpm add @base44/vite-plugin`、`yarn add @base44/vite-plugin`、`bun add @base44/vite-plugin`

## README

# @ base44/vite-plugin (英语)

Base44 应用在沙盒中运行的 Vite 插件 。 提供出错跟踪,HMR通知,可视化编辑,导航跟踪,和遗留的SDK相容性.

## 安装

```bash
npm install @base44/vite-plugin
```

## 使用量

```ts
// vite.config.ts
import base44 from "@base44/vite-plugin";

export default {
  plugins: [
    base44({
      legacySDKImports: false,
      hmrNotifier: true,
      navigationNotifier: true,
      visualEditAgent: true,
    }),
  ],
};
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `legacySDKImports` | `boolean` | `false` | 通过相容层启用遗留的 SDK 导入分辨率 |
| `hmrNotifier` | `boolean` | `false` | 通知HMR更新生命周期的母窗口 |
| `navigationNotifier` | `boolean` | `false` | 跟踪 URL 更改并通知父窗口 |
| `visualEditAgent` | `boolean` | `false` | 启用交互式视觉元素编辑 |

## 建筑

### 插件组成

插件在沙盒中运行时会注册这些子插件( I)`MODAL_SANDBOX_ID` 已设定 :

1.  **基础44** ——核心配置:路径别名 (`@/` → `/src/`),环境变量,依赖优化,以及遗留的SDK导入分辨率.
2.  **iframe-hmr 图像** - 设置中央遥感卫星和 `frame-ancestors` 头可以允许 iframe 嵌入 .
3.  **重叠错误** ——用一个向母窗口报告错误的自定义错误来取代Vite的默认错误. 在 Vite 8 的捆绑dev 模式下( Name`experimental.bundledDev`Vite的客户端从未服务过,所以插件转而关闭了封面并 `sandbox-build-error-notifier` 向父创建错误 `app_error` 形状.
4.  **html注射器** ——在服务时将沙盒侧脚本注入到HTML中. 在捆绑的dev模式下,它的同父异母 **html- 捆绑注入** 在 HTML 捆绑之前注入它们.
5.  **活性注射-生产** ——将分析跟踪器注入生产建设.

德文和出品由维特司令部分出(`serve` 对 `build`),而不是在HTML变换上下文中存在dev服务器——捆绑dev通过构建形状的变换运行HTML,没有通过服务器.

在沙盒外,只有核心插件运行(通过可选的 API 代理支持) `VITE_BASE44_APP_BASE_URL`) (中文(简体) ).

### 云花板工人兼容性

`base44-workerd-compat` 仅调整与 `workerd` 条件,Cloudflare的Vite插件用于服务器代码。 浏览器捆绑 而节点运行的服务器未受影响 。 它既覆盖了Vite的管道 也覆盖了Dev 依赖优化器,用于 Esbuild(第7版)和Rolldown(第8版):

-   **`ws`** 决定: `compat/workerd-ws.cjs`页:1 `ws`\- 形而上学的客户 土生土长的WebSocket. 软件包自有的浏览器只构建了抛出. `WebSocketServer` 也扔出: 服务器代码可以打开套接字但不能听 .
-   **`AsyncLocalStorage.enterWith()`**总是在工作,成为 没有。 称为首次导入的模块 `compat/workerd-enter-with.mjs`编辑 no-op是全局到孤立:任何依赖的代码 `enterWith()` 改为 宣传状态一无所获 默默无闻 而不是例外 使用 `run()`。 。 。 .
-   **`createRequire()` 单位: dev** 取消其参数的查询字符串。 优化 维特的依赖 `?v=` 询问,哪些工人拒绝。 建筑是左边的 单取字节.

舞台手3需要全部三个. `@base44/functions-compiler` 将前两个应用到 后端函数。 云花镇 `nodejs_compat` 旗帜不覆盖其中任何一种: 联合国 `node:http` 客户端无法升级连接, 此连接 `ws` 需求, `enterWith()` 按设计投出,以及 `createRequire()` 拒绝询问.

### 构建状态终点

选入, 仅选入`apply: "serve"`报告最后一个构件的终点 / dev 服务器观察到的编译 / HMR 错误 。 它的存在只是为了让 预览装入后错误的后端民意调查——是 **永远** 页:1 生产建设.

在 dev- server 启动时设置环境变量以启用 :

```bash
BASE44_BUILD_STATUS_ENABLED=1
```

当插件组装其插件列表( 配置负载) 时检查 env var , 所以生成的应用程序 `vite.config.js` 不需要改变。 当它是 未设置, 建置状态子插件根本没有添加到管道中 `configureServer` 钩从来已来.

启用时, 插件服务 :

```
GET /__build_status
```

-   **仅循环后退.** 任何非逾期请求 `remoteAddress` (单位:千美元)`127.0.0.1`, (中文(简体) ), `::1`, (中文(简体) ), `::ffff:127.0.0.1`)掉入,仿佛路线确实 不存在。 无`GET` 方法也会通过.
    
-   **永远 `200`。 。 。 .** 健康生活在身体中,而不是地位规范——a `500` 将会绊倒预览代理服务器自己的错误路径 。 身体为:
    
    ```json
    { "ok": true, "error": null }
    ```
    
    或,当错误尚未解决时:
    
    ```json
    { "ok": false, "error": { "message": "…", "frame": "…", "loc": { "…": 0 } } }
    ```
    
-   **被扫地.** 即使端点是回放( 后端中继) a ,错误是大小封顶和绝对文件系统路径 被剥去到底名.
    
-   **失败开放.** 所有设置和请求处理都包含在内 `try/catch` 这样 此插件中的bug 永远无法打破 dev 服务器 .
    

如何运作: `configureServer` 覆盖 HMR 发送频道 (单位:千美元)`server.hot ?? server.ws`) (中文(简体) ). 一个 `error` 有效载荷记录上一个错误; a 已经成功 `update` 或者说 `full-reload` 释出.

在捆绑的dev模式下,失败永远不会到达该频道——Vite报告它们 通过客户端环境的日志机和每个客户端发送——所以插件 附加记录日志给定的错误, 加上失败 `buildEnd`, (中文(简体) ), 当重建达到的时候 `generateBundle`. 启动时间构建 因此,以这种方式报告失败情况.

**冷启动提醒和范围 .** 出错 _在任何客户端连接之前_ 无法通过 HMR 通道发送, 因此启动时间转换失败可能短暂 读取 `ok: true`。该窗口已被现有的服务器覆盖 `dev_server_error_classifier` (安装 / 启动失败 ) `409`) (中文(简体) ). 这个 结束点的工作是 **装入后 HMR / 编译出错**而不是冷启动失败.

### 路由请求日志( 完整 Stack apps)

唯德无相. 当一个 Nitro 服务器路由服务于一个请求 `X-B44-Request-Id`,每个 `console.*` 打印到 stdout 前缀的行 `[b44-req <id> <level>]` ,然后每请求一行摘要 (单位:千美元)`GET /api/orders handled in 12ms`,或 `threw <Error> after 12ms`) (中文(简体) ). 请求 没有头部没有被触动。 它作为硝基舱运载 `nitro` 属性在 `base44-route-request-log`因为Nitro在一种 单独的运行时间 `console` a Vite 中间软件从未见过.

### 沙盒喷出

单位 **dev 模式**个人 `<script type="module" src="...">` 为每个特性注入标记,直接从 `node_modules`在捆绑的 dev 模式下,标记被注入 `order: "pre"` 相反,它们成为了HTML条目的一部分,被折叠入捆绑(与 `import.meta.hot` 页:1 他们 `src` 是一个 `virtual:base44-vite-plugin/...` id 插件自行解决 `dist/` 目录,所以捆绑不取决于 npm 将包放在哪里.

-   **错误处理器** (单位:千美元)`unhandled-errors-handlers.js`——全球 `error` 财务报告和审定财务报表 `unhandledrejection` 向家长报告的听众 `postMessage`。 。 。 .
-   **挂载观察者** (单位:千美元)`sandbox-mount-observer.js`(b) —— `MutationObserver` 探测仪器元素时的(`data-source-location`) 已交付.
-   **HMR 通知符** (单位:千美元)`sandbox-hmr-notifier.js`)——前进维特 `beforeUpdate`编号 :`afterUpdate` 给父母的事件.
-   **导航通知符** (单位:千美元)`navigation-notifier.js`()——拦截 `pushState`, (中文(简体) ), `replaceState`,以及 `popstate` 以跟踪 URL 变化.
-   **构建错误通知符** (单位:千美元)`sandbox-build-error-notifier.js`,仅捆绑dev)——前进 `vite:error` 给父方的有效载荷 `app_error`,替换无法安装在该模式中的自定义错误覆盖.
-   **HMR 套接字继电器** (单位:千美元)`sandbox-hmr-socket-relay.js`,仅捆绑dev)——集 `window.__base44_bundled_dev__` 和员额 `SANDBOX_WS_CONNECT` 编号 : `SANDBOX_WS_DISCONNECT` 编号 : `sandbox:beforeFullReload`,预览代理服务器的桥通过导入来收集 `/@vite/client`。 。 。 .

这些是自动执行的脚本——它们一旦被浏览器加载就会运行,不需要设置调用.

这个 **视觉编辑代理** 这是例外。 它是一个较大的模块(~560行),通过下列途径分别捆绑 `tsup` 输入 `dist/statics/index.mjs` 通过动态加载 `import()`。这允许本地编程:添加 `?sandbox-bridge=local` 从本地的 HTTPS dev 服务器上装入 `node_modules`。bundled dev 模式不挂载静态中间软件,因此该模式中的插件服务于自身 `dist/` 用于此导入的树( 仅标注和源地图) .

单位 **生产**,取而代之的是内置分析跟踪脚本.

### 服务器提交文档( U)`base44:document`(中文(简体) )

`transformIndexHtml` 从未运行过由框架提供 HTML 文档的应用程序( TanStack Start 和其他 SSR 设置没有) `index.html`) (中文(简体) ). 这些应用程序导入与模块相同的脚本,并将其制入 `<body>`, (中文(简体) ), **在框架自己的脚本之前**数字 :

```jsx
import { Base44Scripts } from "base44:document";

function RootDocument({ children }) {
  return (
    <html>
      <head><HeadContent /></head>
      <body data-react-root="true">
        {children}
        <Base44Scripts />
        <Scripts />
      </body>
    </html>
  );
}
```

该模块是虚拟的:插件从与该模块相同的选项、命令和内存决定其内容 `index.html` 注入,所以 dev 得到沙盒脚本( +) `ssr-mount-signal.js`,在文档解析后报告挂载,因为一个水分页永远不会触发突变观察),生产则得到分析跟踪器。 模块脚本按文档顺序运行, 因此在之前渲染组件 `<Scripts />` 在水合开始前保持错误处理器的注册, 如它们位于 `index.html`永远不要交出来 `<head>`: 预览代理在那里预置了自己的脚本, React 19 失败了它没有渲染出的一个头的水合. `base44DocumentScripts()` 返回原始数据 `{ src, classic? }` 编号 : `{ children }` 列表,键入为 `DocumentScript` 从 `@base44/vite-plugin`,用于制作标记本身的文档。 每个条目显示为 `type="module"` 但有下列情形之一者除外: `classic: true`:沙盒 Dev 服务器为视觉编辑所加载的Tailwind CDN是一个经典脚本.

### 本地开发( 视觉编辑代理)

要在本地的视觉编辑代理上删除 :

1.  生成本地 HTTPS 证书 :
    
    ```bash
    mkcert localhost
    ```
    
2.  启动 Dev 服务器( 带有可选的监视模式) :
    
    ```bash
    npm run dev       # serve dist/statics/ on https://localhost:3201
    npm run dev -- -w # same, with auto-rebuild on changes
    ```
    
3.  添加 `?sandbox-bridge=local` 到您的应用程序的 URL 来加载代理 `localhost:3201` 改为 `node_modules`。 。 。 .
    

### SDK相容性

何时 `legacySDKImports` 已启用,导入 `/entities`, (中文(简体) ), `/functions`, (中文(简体) ), `/integrations`,以及 `/agents` 解析到兼容模块 `compat/`。这些用途 `Proxy` 用于给 Base44 SDK 客户端的路由调用对象.

## 大楼

```bash
npm run build          # TypeScript compilation (plugin)
npm run build:bridge   # tsup bundle (bridge ES module for browsers)
```

## 服务器侧静态入侵 TCP

只有服务器 `base44:runtime` 模块导出 `staticEgress.connect(address, options?)`它代表TCP的助手 安装在Base44的全垒打上 上传包装; Vite 不打开套接字或读取工作空间配置 建立时间。 缺少帮助者以重建/重新部署拒绝的部署 错误。 本地开发没有注入的帮助不会回到 直通TCP(直通TCP).

```ts
import { staticEgress } from "base44:runtime";
const socket = await staticEgress.connect({ hostname: "sftp.example.com", port: 2222 });
// Use the streams with a compatible SSH client; preserve host-key verification.
await socket.close();
```

需要辅助平台 TCP 运行时间和启用的工作空间静态进取 配置 。 更新此插件后重建 。 目前只有原始 TCP (单位:千美元)`secureTransport: "off"`,默认值)得到支持; SSH 提供自己的 加密 TLS和STARTLS 选项拒绝,直到明确支持.

## 私人数据来源`base44:private-data-sources/*`(中文(简体) )

服务器代码达到工作空间的私有数据源,导入相同a 后端函数使用 : `postgres`, (中文(简体) ), `mysql`, (中文(简体) ), `mariadb`, (中文(简体) ), `http`, (中文(简体) ), `elasticsearch`, (中文(简体) ), `sqlserver`, (中文(简体) ), `redis`, (中文(简体) ), `mongodb` 财务报告和审定财务报表 `oracle`,每个来自 `base44:private-data-sources/<type>`模块是此软件包的复制件 后端功能适配器,读取工人的绑定和 `BASE44_PRIVATE_DATA_SOURCES` 标 出 `env` 从 `cloudflare:workers`。 。 。 .

```js
import { Connection } from "tedious";
import { sqlserver } from "base44:private-data-sources/sqlserver";
const source = sqlserver("My-SQL-Server");
const connection = new Connection({
  server: source.host,
  authentication: { type: "default", options: { userName: source.username, password: source.password } },
  options: { database: source.database, encrypt: false, connector: source.tediousConnector() },
});
```

约束只存在于部署的工人身上。 地方发展和 编辑器预览一个搜索抛出, 说发布时有源文件 应用。 客户端导入失败 , 因为来源带有证书 .

## 许可证

麻省理工学院

## 常见问题

### @base44/vite-plugin 是什么？

基于 Base44 应用程序的 Vite 插件

### 如何安装 @base44/vite-plugin？

在项目目录运行 npm install @base44/vite-plugin，或使用 pnpm add / yarn add / bun add。

### @base44/vite-plugin 支持 TypeScript 吗？

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

### @base44/vite-plugin 支持 ESM 还是 CommonJS？

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

### @base44/vite-plugin 可以商用吗？

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

### @base44/vite-plugin 的下载量有多少？

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

### @base44/vite-plugin 还在维护吗？

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