@base44/vite-plugin

中文文档

1.0.52发布于 2026/11/04MITES Module近 30 天下载 1028.2万

基于 Base44 应用程序的 Vite 插件

文档目录16 节

安装
使用量
选项
建筑
插件组成
云花板工人兼容性
构建状态终点
路由请求日志( 完整 Stack apps)
沙盒喷出
服务器提交文档( U) base44:document (中文(简体) )
本地开发( 视觉编辑代理)
SDK相容性
大楼
服务器侧静态入侵 TCP
私人数据来源 base44:private-data-sources/* (中文(简体) )
许可证

@ base44/vite-plugin (英语)

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

安装

npm install @base44/vite-plugin

使用量

// 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 已设定 :

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

德文和出品由维特司令部分出(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 启动时设置环境变量以启用 :

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 将会绊倒预览代理服务器自己的错误路径。身体为:
```
{ "ok": true, "error": null }
```
或,当错误尚未解决时:
```
{ "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>, (中文(简体) ), 在框架自己的脚本之前数字 :

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是一个经典脚本.

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

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

生成本地 HTTPS 证书 :
```
mkcert localhost
```

启动 Dev 服务器( 带有可选的监视模式) :

npm run dev       # serve dist/statics/ on https://localhost:3201
npm run dev -- -w # same, with auto-rebuild on changes

添加 ?sandbox-bridge=local 到您的应用程序的 URL 来加载代理 localhost:3201 改为 node_modules。。。 .

SDK相容性

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

大楼

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).

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。。。 .

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 共发布 89 个版本，首次发布于 2025/10/31；过去 12 个月发布了 84 个版本。

版本	发布日期	距今
`1.0.52`latest	2026/11/04	3 天前
`1.0.51`	2026/11/04	3 天前
`1.0.50`	2026/10/28	10 天前
`1.0.49`	2026/10/28	10 天前
`1.0.48`	2026/10/25	13 天前
`1.0.47`	2026/10/15	23 天前

其他发布通道：next → 1.0.41-rc.0。

关于 @base44/vite-plugin 的常见问题

@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 和提交记录判断。

npm install @base44/vite-plugin

pnpmpnpm add @base44/vite-plugin
yarnyarn add @base44/vite-plugin
bunbun add @base44/vite-plugin

在你的项目目录中运行此命令。

近 30 天下载

10,281,964

约 1028.2万次日均 342,732 次

统计周期 2026/10/08 – 2026/11/06
数据来自 npm 官方下载统计，今天更新

最新版本1.0.52发布于 3 天前

开源许可MIT宽松许可

包体积1.2 MB344 个文件 · 解压后

运行依赖4 个

模块格式ES Module

TypeScript未声明类型可查找 @types/base44__vite-plugin

发布版本89 个近 12 个月 84 个

首次发布2025/10/311 年前

元数据更新2026/11/04

每一个软件包背后，
都有分享与创造的人。