API 参考

`new UtooProject(options)`

创建一个新的项目实例。

选项

选项	类型	描述
`cwd`	string	必填。作为项目根目录在真实文件系统中的绝对路径（例如 `/my-app`）。
`workerUrl`	string	必填。 `Project` 实例核心逻辑实际运行的 Worker 线程 URL。主线程的 `Project` 对象是一个代理，将任务委托给该 Worker。
`threadWorkerUrl`	string	必填。用于处理打包和编译等 CPU 密集型任务的独立 Worker 线程 URL。
`loaderWorkerUrl`	string	用于处理 webpack loader 的独立 Worker 线程 URL。
`wasmUrl`	string	WASM 二进制文件的 URL。默认使用捆绑的二进制文件。
`serviceWorker`	object	用于预览功能的 Service Worker 配置。参见下方子选项。
`logFilter`	string	追踪日志的过滤字符串。
`loadersImportMap`	object	用于配置 Webpack loader 导入的映射表。键为 loader 名称，值为 UMD/CommonJS 模块 URL 或内容字符串。

serviceWorker 子选项：

选项	类型	描述
`url`	string	必填。 Service Worker 脚本的 URL。
`scope`	string	必填。 Service Worker 拦截请求的 URL 范围。
`targetDirToCwd`	string	从目标目录到项目根目录的路径。

文件系统方法

这些方法是异步的，模拟 Node.js fs API。

project.writeFile(path, content, encoding?)

将内容写入真实文件系统中的文件。如果文件不存在，将会创建。

参数	类型	描述
`path`	string	文件的绝对路径（例如 `/src/index.js`）。
`content`	string \| Uint8Array	要写入的内容。
`encoding`	string	编码格式（例如 `'utf8'`）。可选。

project.readFile(path, encoding?)

读取文件的内容。

参数	类型	描述
`path`	string	文件的路径。
`encoding`	string	文件的编码格式（例如 `'utf8'`）。如果未提供，返回 `Uint8Array`。

返回值： Promise<string>（带编码）或 Promise<Uint8Array>（不带编码）。

project.readdir(path, options?)

读取目录的内容。

参数	类型	描述
`path`	string	目录的路径。
`options.recursive`	boolean	如果为 `true`，递归读取。

返回值： Promise<Dirent[]> — 一个 Dirent 对象数组，包含 name、isDirectory() 和 isFile() 方法。

project.mkdir(path, options?)

创建新目录。

参数	类型	描述
`path`	string	要创建的目录路径。
`options.recursive`	boolean	如果为 `true`，按需创建父目录。

project.rm(path, options?)

删除文件或目录。

参数	类型	描述
`path`	string	要删除的文件或目录路径。
`options.recursive`	boolean	如果为 `true`，执行递归删除。

project.rmdir(path, options?)

删除目录。

参数	类型	描述
`path`	string	要删除的目录路径。
`options.recursive`	boolean	如果为 `true`，递归删除。

project.copyFile(src, dst)

从源路径复制文件到目标路径。

参数	类型	描述
`src`	string	源文件路径。
`dst`	string	目标文件路径。

project.stat(path)

获取文件/目录的状态信息。

参数	类型	描述
`path`	string	文件或目录的路径。

返回值： Promise<Stats> — Stats 对象，包含 size、isDirectory()、isFile()、时间戳（atime、mtime、ctime、birthtime）等。

依赖管理

project.deps(options?)

从项目的 package.json 解析依赖并生成 lock 文件字符串。这使得在浏览器中直接进行依赖解析成为可能，无需预先存在的 package-lock.json。

选项	类型	描述
`registry`	string	npm registry URL。默认值：`https://registry.npmmirror.com`
`concurrency`	number	最大并发网络请求数。默认值：`20`

返回值： Promise<string> — 表示已解析的依赖 lock 文件的 JSON 字符串，兼容 package-lock.json 格式。

示例：

app.ts


// 使用默认 registry (npmmirror)
const lockFile = await project.deps();
 
// 使用官方 npm registry
const lockFile = await project.deps({
    registry: "https://registry.npmjs.org"
});
 
// 使用私有 registry 并自定义并发数
const lockFile = await project.deps({
    registry: "https://npm.mycompany.com",
    concurrency: 10
});

project.install(packageLockJsonString, options?)

根据 lock 文件字符串填充 node_modules 目录。

参数	类型	描述
`packageLockJsonString`	string	依赖 lock 文件的 JSON 字符串（来自 `deps()` 或 `package-lock.json` 文件）。
`options.maxConcurrentDownloads`	number	最大并发包下载数。
`options.omit`	string[]	要忽略的依赖类型。可选值：`"dev"`、`"optional"`。

示例：

app.ts


// 基本安装
await project.install(lockFile);
 
// 带并发限制的安装
await project.install(lockFile, { maxConcurrentDownloads: 10 });
 
// 不安装开发依赖（生产模式）
await project.install(lockFile, { omit: ["dev"] });

构建与开发

project.build()

在线程 Worker 中触发构建过程。它从项目根目录的 utoopack.json 读取构建配置，并基于该配置运行打包器。

返回值： Promise<BuildOutput> — 包含 issues 数组的对象，其中包含任何构建警告或错误。

app.ts


const result = await project.build();
if (result.issues.length > 0) {
  console.warn("构建完成，但存在问题：", result.issues);
}

project.dev(onUpdate?)

启动带文件监听的开发模式。当文件变更时自动触发增量重建。

参数	类型	描述
`onUpdate`	function	每次重建完成时调用的回调函数，接收 `BuildOutput`。可选。

app.ts


project.dev((result) => {
  console.log("重建完成，问题：", result.issues);
});

project.hmrSubscribe(identifier, callback)

订阅特定标识符的 HMR（热模块替换）事件。

参数	类型	描述
`identifier`	string	要订阅的模块标识符。
`callback`	function	当模块发生变更时，接收更新指令调用。

project.updateInfoSubscribe(aggregationMs, callback)

订阅编译生命周期事件（开始/结束）。

参数	类型	描述
`aggregationMs`	number	聚合时间间隔，单位为毫秒。
`callback`	function	在编译事件发生时接收 `UpdateMessage` 调用。

预览功能

project.installServiceWorker()

注册并激活构造函数中定义的 Service Worker。这对于预览功能至关重要。

类型定义

BuildOutput


interface BuildOutput {
  issues: Issue[];
}

InstallOptions


interface InstallOptions {
  maxConcurrentDownloads?: number;
  omit?: ("dev" | "optional")[];
}

DepsOptions


interface DepsOptions {
  registry?: string;
  concurrency?: number;
}

Dirent


class Dirent {
  name: string;
  isDirectory(): boolean;
  isFile(): boolean;
}

Stats


class Stats {
  size: number;
  isDirectory(): boolean;
  isFile(): boolean;
  atime: Date;
  mtime: Date;
  ctime: Date;
  birthtime: Date;
}