已弃用 _{(活跃分支：ZenFS)}

2024年3月22日

大家好，我是BrowserFS的当前维护者。

我已经为BrowserFS工作了一年多，并做出了一些重大改进。

几个月前，我开始将一些后端从BrowserFS分离出来，放到不同的包中。同时，我在Github上创建了browser-fs组织，在NPM上创建了browserfs组织。我创建新组织是为了保持仓库和包的组织性。另一个原因是项目的原作者John Vilk已经没有时间管理项目了。这意味着在写这篇文章时，我仍然无法访问NPM包。

我感觉现在项目已经发生了如此重大的变化，以至于它不再是原来的BrowserFS了。甚至名字BrowserFS也暗示它是为浏览器设计的，而它已经超越了这个范围。因此，我认为这个项目应该是全新的，但仍然传承BrowserFS的遗产。我决定将其命名为ZenFS，因为我的核心目标是易用性和安心感。

1675年，艾萨克·牛顿在给罗伯特·胡克的一封信中famously写道："如果我看得更远，那是因为我站在巨人的肩膀上"。这句话在ZenFS的case中绝对是正确的。如果没有BrowserFS的创建，我就不会发现它并对Typescript/Javascript中的完整文件系统感到惊叹。

我要向Emery Berger博士表示最深切的感谢。在我向BrowserFS提交第一个pull request后不久，我就联系他询问是否可以成为项目的维护者。Berger博士欢迎我成为项目的维护者，并在其他一些事务上给予了极大的帮助。

非常感谢社区通过提交issues和pull requests来帮助我完成这个项目。

NPM组织browserfs的所有包都已被弃用，并附有指向新包和此通知的消息。所有在@browserfs下发布的版本也已在@zenfs下发布。

我希望ZenFS能够继承BrowserFS的遗产，并达到同样的受欢迎程度和可靠性。

再会，
James Prevett
BrowserFS维护者
ZenFS创建者

BrowserFS

BrowserFS是一个浏览器内文件系统，它模拟了Node JS文件系统API，并支持从各种后端存储和检索文件。BrowserFS还能很好地集成到Emscripten文件系统中。

后端

BrowserFS具有高度可扩展性，并附带了许多文件系统后端：

• HTTPRequest：使用fetch按需从Web服务器下载文件。
• LocalStorage：将文件存储在浏览器的localStorage中。
• IndexedDB：将文件存储到浏览器的IndexedDB对象数据库中。
• Dropbox：将文件存储到用户的Dropbox账户中。
  • 注意：您需要为这个文件系统提供一个已认证的DropboxJS V2 JS SDK客户端。
• InMemory：将文件存储在内存中。因此，它是一个临时文件存储，当用户离开页面时会被清除。
• ZipFS：只读的基于zip文件的文件系统。在您访问文件时懒加载解压。
  • 开箱即支持DEFLATE。
  • 有超级老的zip文件？browserfs-zipfs-extras包增加了对EXPLODE、UNREDUCE和UNSHRINK的支持。
• IsoFS：将.iso文件挂载到文件系统中。
  • 支持Microsoft Joliet和Rock Ridge对ISO9660标准的扩展。
• WorkerFS：让您可以在WebWorker中挂载主线程中配置的BrowserFS文件系统，或反之亦然！
• MountableFileSystem：让您可以将多个文件系统挂载到单个目录层次结构中，就像在类Unix操作系统中一样。
• OverlayFS：通过在只读文件系统上覆盖一个可写文件系统来将其挂载为可读写。类似于Docker的overlayfs，它只会将更改的文件写入可写文件系统。
• AsyncMirror：同步使用异步后端。对Emscripten来说非常宝贵；让您的Emscripten应用程序无需额外努力就能写入更大的文件存储！
  • 注意：在构建期间将整个文件系统的内容加载到同步后端。在内存中执行同步操作，并将它们排队以镜像到异步后端。
• FolderAdapter：包装一个文件系统，并将所有交互限定在该文件系统的子文件夹中。
• Emscripten：让您可以在BrowserFS内挂载Emscripten文件系统。

更多后端可以由单独的库定义，只要它们扩展并实现BrowserFS.FileSystem。多个后端可以同时在目录层次结构的不同位置活动。

有关更多信息，请参阅BrowserFS的API文档。

构建

先决条件：

• Node和NPM
• 运行npm install（或使用您的包管理器的等效命令）来安装本地依赖项。

运行npm run build后，您可以在dist目录中找到构建好的版本。

自定义构建（不推荐）：

如果您想使用可用后端的子集构建BrowserFS， 请更改src/core/backends.ts以仅包含您需要的后端， 然后重新构建。

使用

🛈 这些示例是用ESM编写的。如果您不使用ESM，可以在HTML中添加<script src="browserfs.min.js"></script>，然后通过全局BrowserFS对象使用BrowserFS。

BrowserFS提供了一个方便的configure函数，您可以使用它轻松配置BrowserFS以使用各种文件系统类型。

这里是一个使用基于LocalStorage的文件系统的简单示例：

import { configure, BFSRequire } from 'browserfs';

// 您也可以在最后一个参数中添加回调，而不是使用promise
await configure({ fs: 'LocalStorage' });

const fs = BFSRequire('fs');

// 现在，您可以像这样编写代码：

fs.writeFile('/test.txt', 'Cool, I can do this in the browser!', function (err) {
	fs.readFile('/test.txt', function (err, contents) {
		console.log(contents.toString());
	});
});

以下代码将zip文件挂载到/zip，内存存储挂载到/tmp，以及IndexedDB浏览器本地存储挂载到/home：

import { configure, BFSRequire } from 'browserfs';
import Buffer from 'buffer';

const zipData = await (await fetch('mydata.zip')).arrayBuffer();

await configure({
	fs: 'MountableFileSystem',
	options: {
		'/mnt/zip': {
			fs: 'ZipFS',
			options: {
				zipData: Buffer.from(zipData)
			}
		},
		'/tmp': { fs: 'InMemory' },
		'/home': { fs: 'IndexedDB' }
	}
};

与Browserify和Webpack一起使用

BrowserFS作为UMD模块发布，所以您可以在网页中通过script标签包含它，也可以用您喜欢的JavaScript模块打包器打包它。

您还可以使用BrowserFS为您的应用程序提供fs、path和buffer模块，以及Buffer和process全局变量。BrowserFS包含了fs、buffer、path和process的shim模块，您可以在Webpack和Browserify中使用。

Webpack:

module.exports = {
	resolve: {
		// 使用我们的Node模块版本。
		alias: {
			fs: 'browserfs/dist/shims/fs.js',
			buffer: 'browserfs/dist/shims/buffer.js',
			path: 'browserfs/dist/shims/path.js',
			processGlobal: 'browserfs/dist/shims/process.js',
			bufferGlobal: 'browserfs/dist/shims/bufferGlobal.js',
			bfsGlobal: require.resolve('browserfs'),
		},
	},
	// 必需，以避免"Uncaught TypeError: BrowserFS.BFSRequire is not a function"问题
	// 参见：https://github.com/jvilk/BrowserFS/issues/201
	module: {
		noParse: /browserfs\.js/,
	},
	plugins: [
		// 暴露BrowserFS、process和Buffer全局变量。
		// 注意：如果您打算在script标签中使用BrowserFS，则不需要
		// 暴露BrowserFS全局变量。
		new webpack.ProvidePlugin({ BrowserFS: 'bfsGlobal', process: 'processGlobal', Buffer: 'bufferGlobal' }),
	],
	// 禁用Webpack的内置process和Buffer polyfills！
	node: {
		process: false,
		Buffer: false,
	},
};

Browserify:

var browserfsPath = require.resolve('browserfs');
var browserifyConfig = {
	// 覆盖Browserify的buffer/fs/path内置模块。
	builtins: Object.assign({}, require('browserify/lib/builtins'), {
		buffer: require.resolve('browserfs/dist/shims/buffer.js'),
		fs: require.resolve('browserfs/dist/shims/fs.js'),
		path: require.resolve('browserfs/dist/shims/path.js'),
	}),
	insertGlobalVars: {
		// process、Buffer和BrowserFS全局变量。
		// 如果您在script标签中包含browserfs.js，
		// 则不需要BrowserFS全局变量。
		process: function () {
			return "require('browserfs/dist/shims/process.js')";
		},
		Buffer: function () {
			return "require('buffer').Buffer";
		},
		BrowserFS: function () {
			return "require('" + browserfsPath + "')";
		},
	},
};

与Node一起使用

您可以在Node中使用BrowserFS。只需将browserfs添加为NPM依赖项，然后require('browserfs')。 这个操作返回的对象与上面描述的BrowserFS全局变量相同。

如果您需要BrowserFS返回Node Buffer对象（而不是实现相同接口的对象）， 只需require('browserfs/dist/node/index')即可。

与Emscripten一起使用

您可以在Emscripten中使用任何_同步_的BrowserFS文件系统！ 将Emscripten文件系统中的特定文件夹持久化到localStorage，或者使Emscripten能够在请求时同步下载另一个文件夹中的文件。 在页面中引入 browserfs.min.js，并在运行 Emscripten 代码之前配置 BrowserFS。然后，将类似以下代码添加到 Module 的 preRun 数组中：

/**
 * 将基于 localStorage 的文件系统挂载到 Emscripten 文件系统的 /data 文件夹中。
 */
function setupBFS() {
	// 获取 BrowserFS Emscripten FS 插件。
	var BFS = new BrowserFS.EmscriptenFS();
	// 创建将作为挂载点的文件夹。
	FS.createFolder(FS.root, 'data', true, true);
	// 将 BFS 的根文件夹挂载到 '/data' 文件夹。
	FS.mount(BFS, { root: '/' }, '/data');
}

注意：在包含 Emscripten 应用程序的页面上，请不要使用 BrowserFS.install(window)！这会误导 Emscripten 认为它正在 Node JS 中运行。

如果你希望在 Emscripten 中使用异步 BrowserFS 后端（例如 Dropbox），你需要先将其包装到 AsyncMirror 文件系统中：

/**
 * 在启动 Emscripten 模块之前运行此函数。
 * @param dropboxClient 一个已认证的 DropboxJS 客户端。
 */
function asyncSetup(dropboxClient, cb) {
	// 这将 Dropbox 包装在 AsyncMirror 文件系统中。
	// BrowserFS 会将 Dropbox 的所有内容下载到
	// 内存文件系统中，并同步两者的操作以保持同步。
	BrowserFS.configure(
		{
			fs: 'AsyncMirror',
			options: {
				sync: {
					fs: 'InMemory',
				},
				async: {
					fs: 'Dropbox',
					options: {
						client: dropboxClient,
					},
				},
			},
		},
		cb
	);
}
function setupBFS() {
	// 获取 BrowserFS Emscripten FS 插件。
	var BFS = new BrowserFS.EmscriptenFS();
	// 创建将作为挂载点的文件夹。
	FS.createFolder(FS.root, 'data', true, true);
	// 将 BFS 的根文件夹挂载到 '/data' 文件夹。
	FS.mount(BFS, { root: '/' }, '/data');
}

测试

要运行单元测试，只需执行 npm test。

引用

BrowserFS 是麻省大学阿默斯特分校 PLASMA 实验室的 Doppio 和 Browsix 研究项目的组成部分。如果你决定在一个可能导致发表的项目中使用 BrowserFS，请引用关于 Doppio 和 Browsix 的学术论文：

John Vilk 和 Emery D. Berger。Doppio：打破浏览器语言障碍。发表于 第35届ACM SIGPLAN编程语言设计与实现会议论文集 (2014)，第508-518页。

@inproceedings{VilkDoppio,
	author		= {John Vilk and
							 Emery D. Berger},
	title		 = {{Doppio: Breaking the Browser Language Barrier}},
	booktitle = {Proceedings of the 35th {ACM} {SIGPLAN} Conference on Programming Language Design and Implementation},
	pages		 = {508--518},
	year			= {2014},
	url			 = {http://doi.acm.org/10.1145/2594291.2594293},
	doi			 = {10.1145/2594291.2594293}
}

Bobby Powers、John Vilk 和 Emery D. Berger。Browsix：连接 Unix 和浏览器之间的鸿沟。发表于 第二十二届编程语言和操作系统架构支持国际会议论文集 (2017)，第253-266页。

@inproceedings{PowersBrowsix,
	author		= {Bobby Powers and
							 John Vilk and
							 Emery D. Berger},
	title		 = {{Browsix: Bridging the Gap Between Unix and the Browser}},
	booktitle = {Proceedings of the Twenty-Second International Conference on Architectural
							 Support for Programming Languages and Operating Systems},
	pages		 = {253--266},
	year			= {2017},
	url			 = {http://doi.acm.org/10.1145/3037697.3037727},
	doi			 = {10.1145/3037697.3037727}
}

许可证

BrowserFS 采用 MIT 许可证。详情请参阅 LICENSE 文件。