在Node.js应用里处理文件上传、编译缓存或测试夹具时，往往需要一块不会被其他进程干扰的存储空间。fs.mkdtemp正是为此设计的API，它会在操作系统的临时目录中新建一个名称唯一、带有随机字符的文件夹，调用方拿到路径后就可以放心写入中间数据，而不必担心和同机其他任务撞名。
fs.mkdtemp的基本用法与参数解析
fs.mkdtemp隶属于Node.js的fs模块，其函数签名要求第一个参数是一个目录前缀字符串，例如os.tmpdir() + '/myapp-'。底层实现会在这个前缀后面追加六个由系统生成的随机字符，从而保证目录名的全局唯一性。开发者需要注意，前缀必须以路径分隔符结尾，否则随机串会直接连在前缀最后一个字符后，可能导致目录层级错误。
异步版本通过回调或Promise返回新建目录的绝对路径。下面代码展示了使用util.promisify后的写法，先引入必要模块，再拼接前缀并创建目录：
const fs = require('fs');
const os = require('os');
const path = require('path');
const { promisify } = require('util');
const mkdtemp = promisify(fs.mkdtemp);
async function createTemp() {
const prefix = path.join(os.tmpdir(), 'myapp-');
const dir = await mkdtemp(prefix);
console.log('临时目录已创建：' + dir);
return dir;
}
createTemp().catch(console.error);
同步接口fs.mkdtempSync逻辑相同，但会阻塞事件循环，适合在脚本启动阶段或CLI工具中使用。如果前缀未以分隔符结尾，在Windows上可能生成类似C:UsersxxxAppDataLocalTempmyappXYZABC的目录，而在Unix-like系统上则成为/tmp/myappXYZABC，虽然仍能创建成功，但不如明确分层直观。
为何选择mkdtemp而非手动拼接时间戳
不少初学者习惯用Date.now()拼接目录名，认为毫秒数足够避免冲突。但在高并发场景或同一毫秒内多次调用的循环中，这种方案极易产生同名路径，后续写入会覆盖先前数据。mkdtemp调用的是libuv底层的mkdtemp C函数，随机串由系统熵池生成，碰撞概率远低于人工方案，并且不需要开发者自己处理重试逻辑。
另一方面，手动管理临时目录常忘记清理，时间一长临时分区就被占满。结合mkdtemp返回的绝对路径，我们可以在任务结束时用fs.rm(dir, { recursive: true, force: true })整棵删除。下面的例子演示了写入文件后自动清理的模式：
const fs = require('fs').promises;
const os = require('os');
const path = require('path');
async function withTempDir() {
const base = await fs.mkdtemp(path.join(os.tmpdir(), 'task-'));
const file = path.join(base, 'data.txt');
await fs.writeFile(file, '临时内容');
// 使用完成后清理
await fs.rm(base, { recursive: true, force: true });
console.log('已清理：' + base);
}
withTempDir().catch(console.error);
从权限角度看，mkdtemp创建的目录默认模式为0700，意味着只有当前用户可读写执行，这比在共享临时区放一个全局可写目录安全得多。若业务需要其他用户访问，可在创建后调用fs.chmod调整，但一般临时中间文件没必要放开权限。
异常场景与跨平台注意事项
当临时文件系统被挂载为只读，或磁盘inode耗尽时，mkdtemp会抛出EACCES或ENOSPC错误。健壮的代码应当捕获这些异常并提示运维，而不是让进程崩溃。在Docker容器里，os.tmpdir()通常指向/tmp，但若镜像用NODE_OPTIONS或环境变量改了临时根，mkdtemp也会随之变化，因此不要硬编码/tmp路径。
Windows平台存在路径长度限制，前缀过长可能导致最终路径超出260字符而失败。建议前缀控制在十余字符内，并利用path.join而非字符串相加来自动适配分隔符。此外，防病毒软件有时会扫描刚建立的空目录，造成极短暂锁定，若立即写入大文件偶发EBUSY，加一次重试即可缓解。
const fs = require('fs').promises;
const os = require('os');
const path = require('path');
async function safeMkdtemp(retry = 3) {
const prefix = path.join(os.tmpdir(), 'safe-');
for (let i = 0; i < retry; i++) {
try {
return await fs.mkdtemp(prefix);
} catch (e) {
if (e.code === 'EBUSY' && i < retry - 1) {
await new Promise(r => setTimeout(r, 50));
continue;
}
throw e;
}
}
}
最后提醒，mkdtemp只负责建目录，不负责过期回收。长期运行的Node服务若频繁建临时目录却忘记删，依然会堆积垃圾。可搭配定时任务或进程退出钩子process.on('exit')统一扫尾，确保临时空间始终可控。
Node.jsfs.mkdtemp临时目录修改时间：2026-08-13 06:45:25