百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
Y

yazl

> 编程语言
开源

另一个用于 node 的 zip 库

381 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

另一个用于 node 的 zip 库

yazl

yet another zip library for node. For unzipping, see yauzl.

Design principles:

  • Don't block the JavaScript thread. Use and provide async APIs.
  • Keep memory usage under control. Don't attempt to buffer entire files in RAM at once.
  • Prefer to open input files one at a time than all at once. This is slightly suboptimal for time performance, but avoids OS-imposed limits on the number of simultaneously open file handles.

Usage

…

API

Class: ZipFile

new ZipFile()

No parameters. Nothing can go wrong.

addFile(realPath, metadataPath, [options])

Adds a file from the file system at realPath into the zipfile as metadataPath. Typically metadataPath would be calculated as path.relative(root, realPath). Unzip programs would extract the file from the zipfile as metadataPath. realPath is not stored in the zipfile.

A valid metadataPath must not be blank. If a metadataPath contains "\\" characters, they will be replaced by "/" characters. After this substitution, a valid metadataPath must not start with "/" or /[A-Za-z]:\//, and must not contain ".." path segments. File paths must not end with "/", but see addEmptyDirectory(). After UTF-8 encoding, metadataPath must be at most 0xffff bytes in length.

options may be omitted or null and has the following structure and default values:

javascript
{
  mtime: stats.mtime,
  mode: stats.mode,
  compress: true,
  compressionLevel: 6,
  forceZip64Format: false,
  forceDosTimestamp: false,
  fileComment: "", // or a UTF-8 Buffer
}

Use mtime and/or mode to override the values that would normally be obtained by the fs.Stats for the realPath. The mode is the unix permission bits and file type. The mtime and mode are stored in the zip file in the fields "last mod file time", "last mod file date", and "external file attributes". yazl does not store group and user ids in the zip file.

If compress is true, the file data will be deflated (compression method 8). If compress is false, the file data will be stored (compression method 0). If compressionLevel is specified, it will be passed to zlib. Specifying compressionLevel: 0 is equivalent to compress: false. If both compress and compressionLevel are given, asserts that they do not conflict, i.e. !!compress === !!compressionLevel.

If forceZip64Format is true, yazl will use ZIP64 format in this entry's Data Descriptor and Central Directory Record even if not needed (this may be useful for testing.). Otherwise, yazl will use ZIP64 format where necessary.

Since yazl version 3.3.0, yazl includes the Info-ZIP "universal timestamp" extended field (0x5455 aka "UT") to encode the mtime. The Info-ZIP timestamp is a more modern encoding for the mtime and is generally recommended. Set forceDosTimestamp to true to revert to the pre-3.3.0 behvior, disabling this extended field. The DOS encoding is always included regardless of this option, because it is required in the fixed-size metadata of every archive entry. The benefits of the Info-ZIP encoding include: timezone is specified as always UTC, which is better for cloud environments and any teams working in multiple timezones; capable of encoding "time 0", the unix epoch in 1970, which is better for some package managers; the precision is 1-second accurate rather than rounded to the nearest even second. The disadvantages of including this field are: it requires an extra 9 bytes of metadata per entry added to the archive.

When attempting to encode an mtime outside the supported range for either format, such as the year 1970 in the DOS format or the year 2039 for the modern format, the time will clamped to the closest supported time.

If fileComment is a string, it will be encoded with UTF-8. If fileComment is a Buffer, it should be a UTF-8 encoded string. In UTF-8, fileComment must be at most 0xffff bytes in length. This becomes the "file comment" field in this entry's central directory file header.

Internally, fs.stat() is called immediately in the addFile function, and fs.createReadStream() is used later when the file data is actually required. Throughout adding and encoding n files with addFile(), the number of simultaneous open files is O(1), probably just 1 at a time.

addReadStream(readStream, metadataPath, [options])

Adds a file to the zip file whose content is read from readStream. This method is effectively implemented as this.addReadStreamLazy(metadataPath, options, cb => cb(null, readStream)).

In general, it is recommended to use addReadStreamLazy instead of this method to avoid holding a large number of system resources open for a long time. This method is provided for backward compatibility, and for convenience in cases where the readStream doesn't require meaningful resources to hold open and waiting.

addReadStreamLazy(metadataPath[, options], getReadStreamFunction)

Adds a file to the zip file whose content is read from a read stream obtained by calling getReadStreamFunction(cb). getReadStreamFunction(cb) is called with a single callback function. Your implementation of getReadStreamFunction should eventually call cb(err, readStream) and give the readStream that provides the contents of the file to add to the zip file. If err is given (if it is truthy), it will be emitted from this ZipFile object. The return value from cb is unspecified.

See addFile() for the meaning of the metadataPath parameter. typeof getReadStreamFunction must be 'function', which is used to determine when options has been omitted. options may be omitted or null and has the following structure and default values:

javascript
{
  mtime: new Date(),
  mode: 0o100664,
  compress: true,
  compressionLevel: 6,
  forceZip64Format: false,
  forceDosTimestamp: false,
  fileComment: "", // or a UTF-8 Buffer
  size: 12345, // example value
}

See addFile() for the meaning of mtime, mode, compress, compressionLevel, forceZip64Format, forceDosTimestamp, and fileComment. If size is given, it will be checked against the actual number of bytes in the readStream, and an error will be emitted if there is a mismatch. See the documentation on calculatedTotalSizeCallback for why the size option exists.

Note that yazl will .pipe() data from readStream, so be careful using .on('data'). In certain versions of node, .on('data') makes .pipe() behave incorrectly.

Here's an example call to this method to illustrate the function callbacks:

javascript
zipfile.addReadStreamLazy("path/in/archive.txt", function(cb) {
  var readStream = getTheReadStreamSomehow();
  cb(null, readStream);
});

addBuffer(buffer, metadataPath, [options])

Adds a file to the zip file whose content is buffer. See below for info on the limitations on the size of buffer. See addFile() for info about the metadataPath parameter. options may be omitted or null and has the following structure and default values:

javascript
{
  mtime: new Date(),
  mode: 0o100664,
  compress: true,
  compressionLevel: 6,
  forceZip64Format: false,
  forceDosTimestamp: false,
  fileComment: "", // or a UTF-8 Buffer
}

See addFile() for the meaning of mtime, mode, compress, compressionLevel, forceZip64Format, forceDosTimestamp, and fileComment.

This method has the unique property that General Purpose Bit 3 will not be used in the Local File Header. This doesn't matter for unzip implementations that conform to the Zip File Spec. However, 7-Zip 9.20 has a known bug where General Purpose Bit 3 is declared an unsupported compression method (note that it really has nothing to do with the compression method.). See issue #11. If you would like to create zip files that 7-Zip 9.20 can understand, you must use addBuffer() instead of addFile(), addReadStream(), or addReadStreamLazy() for all entries in the zip file (and addEmptyDirectory() is fine too).

Note that even when yazl provides the file sizes in the Local File Header, yazl never uses ZIP64 format for Local File Headers due to the size limit on buffer (see below).

Size limitation on buffer

In order to require the ZIP64 format for a local file header, the provided buffer parameter would need to exceed 0xfffffffe in length. Alternatively, the buffer parameter might not exceed 0xfffffffe in length, but zlib compression fails to compress the buffer and actually inflates the data to more than 0xfffffffe in length. Both of these scenarios are not allowed by yazl, and those are enforced by a size limit on the buffer parameter.

According to this zlib documentation, the worst case compression results in "an expansion of at most 13.5%, plus eleven bytes". Furthermore, some configurations of Node.js impose a size limit of 0x3fffffff on every Buffer object. Running this size through the worst case compression of zlib still produces a size less than 0xfffffffe bytes,

Therefore, yazl enforces that the provided buffer parameter must be at most 0x3fffffff bytes long.

addEmptyDirectory(metadataPath, [options])

Adds an entry to the zip file that indicates a directory should be created, even if no other items in the zip file are contained in the directory. This method is only required if the zip file is intended to contain an empty directory.

See addFile() for info about the metadataPath parameter. If metadataPath does not end with a "/", a "/" will be appended.

options may be omitted or null and has the following structure and default values:

javascript
{
  mtime: new Date(),
  mode: 040775,
  forceDosTimestamp: false,
}

See addFile() for the meaning of mtime, mode, and forceDosTimestamp.

end([options], [calculatedTotalSizeCallback])

Indicates that no more files will be added via addFile(), addReadStream(), addReadStreamLazy(), addBuffer(), or addEmptyDirectory(), and causes the eventual close of outputStream.

options may be omitted or null and has the following structure and default values:

javascript
{
  forceZip64Format: false,
  comment: "", // or a CP437 Buffer
}

If forceZip64Format is true, yazl will include the ZIP64 End of Central Directory Locator and ZIP64 End of Central Directory Record even if not needed (this may be useful for testing.). Otherwise, yazl will include these structures if necessary.

If comment is a string, it will be encoded with CP437. If comment is a Buffer, it should be a CP437 encoded string. comment must be at most 0xffff bytes in length and must not include the byte sequence [0x50,0x4b,0x05,0x06]. This becomes the ".ZIP file comment" field in the end of central directory record. Note that in practice, most zipfile readers interpret this field in UTF-8 instead of CP437. If your string uses only codepoints in the range 0x20...0x7e (printable ASCII, no whitespace except for single space ' '), then UTF-8 and CP437 (and ASCII) encodings are all identical. This restriction is recommended for maxium compatibility. To use UTF-8 encoding at your own risk, pass a Buffer into this function; it will not be validated.

If specified and non-null, calculatedTotalSizeCallback is given the parameters (calculatedTotalSize) sometime during or after the call to end(). calculatedTotalSize is of type Number and can either be -1 or the guaranteed eventual size in bytes of the output data that can be read from outputStream.

Note that calculatedTotalSizeCallback is usually called well before outputStream has piped all its data; this callback does not mean that the stream is done.

(The calculatedTotalSizeCallback feature was added to this library to support the use case of a web server constructing a zip file dynamica

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

JavaScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言