JSZip的folder()方法何时返回null？求触发场景示例

问题背景 #

给定folder(name)方法的类型签名如下：

/**
 * Returns a new JSZip instance with the given folder as root
 *
 * @param name Name of the folder
 * @return New JSZip object with the given folder as root or null
 */
folder(name: string): JSZip | null;

但官方文档说明：

folder(name)
若目录不存在则创建它，返回以新目录为根的新JSZip对象。
另见file()的dir选项。
返回值： 以新目录为根的新JSZip对象（支持链式调用）。
起始版本： v1.0.0

我编写了如下测试代码，尝试覆盖返回null的分支：

// 读取zip文件并通过JSZip对象处理的函数
// 合法输入应为包含名为"courses"的压缩文件夹，该文件夹是唯一的
// 注：该文件夹下包含存储章节信息的JSON文件

async function extractSections(dSetID: string, zip: JSZip): Promise<Section[]> {
    // 用于收集转换后的章节数据
    const sections: Section[] = [];

    // 从zip中获取名为'courses'的文件夹
    const coursesFolder = zip.folder("courses");
    if (!coursesFolder) {
        throw new Error("Courses folder not found in the zip file.");
    }

    // 遍历文件夹内文件并转换为Section对象，加入数组...
}

我尝试传入不含courses文件夹的zip文件，但错误分支从未触发，程序始终认为coursesFolder不为null。请问如何触发该方法返回null的场景？

解答 #

首先明确：JSZip的folder(name)方法在正常使用场景下（读取现有zip或创建新zip），永远不会返回null。

你看到的类型签名标注返回JSZip | null是类型定义的错误或历史遗留问题，和官方文档的实际行为完全不符。官方文档已经明确说明：无论目标文件夹是否存在，该方法都会返回一个以目标路径为根的JSZip实例——如果文件夹不存在，会自动创建它。

只有传入无效参数时，folder(name)才会返回null，比如：

• 传入null或undefined作为name参数
• 传入空字符串（""）
• 传入包含操作系统非法字符的路径（JSZip本身对路径限制较宽松，这类场景极少）

但这些属于非法调用场景，并非你想要的“检测现有zip中是否存在指定文件夹”的需求。

如果需要判断现有zip里是否存在courses文件夹，不能用folder()的返回值判断，应该改用zip.file("courses/")来检测：

// 检测是否存在courses文件夹
const hasCoursesFolder = !!zip.file("courses/");
if (!hasCoursesFolder) {
    throw new Error("Courses folder not found in the zip file.");
}
// 再获取文件夹实例
const coursesFolder = zip.folder("courses");

因为zip.file("path/")会返回对应的目录条目（存在则返回条目，不存在则返回null），这样就能准确判断目标文件夹是否存在于现有zip中。

内容的提问来源于stack exchange，提问作者Omni Carlos