upath vs path2 vs upath2

跨平台路径处理库的技术选型

path2、upath 和 upath2 都是用于在 Node.js 环境中处理文件系统路径的工具库，旨在解决原生 path 模块在不同操作系统（尤其是 Windows 与 Unix-like 系统）之间行为不一致的问题。它们提供统一的 API 来规范化、解析和操作路径字符串，避免因斜杠方向（/ vs \）或大小写敏感性导致的兼容性问题。这些库常用于构建跨平台 CLI 工具、打包器、静态资源处理器等需要可靠路径操作的场景。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称	下载量	Stars	大小	Issues	发布时间	License
npm包名称	下载量	Stars	大小	Issues	发布时间	License
upath	22,715,492	154	-	3	5 年前	MIT
path2	827,222	25	-	1	12 年前	MIT
upath2	127,172	2	54 kB	1	1 个月前	ISC

跨平台路径处理：path2、upath 与 upath2 深度对比

在 Node.js 开发中，处理文件路径看似简单，实则暗藏陷阱 —— 尤其当代码需同时运行于 Windows（使用反斜杠 \）和 macOS/Linux（使用正斜杠 /）时。原生 path 模块虽能工作，但其输出格式依赖当前操作系统，容易导致配置错误、路径拼接失败或测试不一致。path2、upath 和 upath2 正是为解决这一痛点而生。但三者定位、状态与适用场景大不相同，本文将从实战角度剖析差异。

⚠️ 维护状态：先看是否还能用

path2 已被废弃。根据其 npm 页面明确提示：“This package is deprecated. Please use upath instead.” 官方 GitHub 仓库也已归档，多年无更新。任何新项目都应避开此包，已有项目应尽快迁移。

upath 仍在积极维护，作为社区事实标准，被 Webpack、Vite 等主流工具间接依赖，稳定性经过大规模验证。

upath2 是 upath 的现代化继任者，由同一作者开发，采用 ESM + TypeScript 重构，专为现代 JavaScript 生态设计。

💡 建议：除非维护遗留系统，否则直接在 upath 与 upath2 之间选择。

🔧 核心功能：API 兼容性与路径标准化

三者均提供与 Node.js 原生 path 模块几乎一致的 API（如 join、resolve、normalize），但关键区别在于 输出路径的格式。

原生 `path` 的问题示例

// 在 Windows 上运行
const path = require('path');
console.log(path.join('src', 'components', 'Button.jsx'));
// 输出: src\components\Button.jsx （反斜杠）

// 在 macOS/Linux 上运行
console.log(path.join('src', 'components', 'Button.jsx'));
// 输出: src/components/Button.jsx （正斜杠）

这种不一致性会导致：

配置文件中的路径在 CI/CD 跨平台时失效
字符串匹配（如正则）因分隔符不同而失败
Git 提交中混杂不同风格路径，污染 diff

`upath`：强制统一为 POSIX 风格

无论在哪种系统运行，upath 总是返回正斜杠路径：

// 使用 upath
const upath = require('upath');

console.log(upath.join('src', 'components', 'Button.jsx'));
// 所有平台输出: src/components/Button.jsx

console.log(upath.resolve('..', 'dist')); 
// 所有平台输出类似: /Users/project/dist （正斜杠）

它通过内部调用原生 path 后，再将结果中的 \ 替换为 / 实现标准化。

`upath2`：同样标准化，但仅支持 ESM

upath2 行为与 upath 几乎一致，但导入方式不同：

// 使用 upath2 (ESM only)
import * as upath from 'upath2';

console.log(upath.join('src', 'components', 'Button.jsx'));
// 所有平台输出: src/components/Button.jsx

注意：upath2 不提供 require() 支持。若强行在 CommonJS 中使用，会报错。

`path2`（已废弃）：历史行为

// path2 (不推荐！仅作对比)
const path2 = require('path2');

console.log(path2.join('src', 'components', 'Button.jsx'));
// 曾尝试标准化，但实现不如 upath 成熟，且已停止维护

📦 模块系统支持：CommonJS 还是 ESM？

这是 upath 与 upath2 的核心分水岭。

包名	CommonJS (`require`)	ESM (`import`)	TypeScript 类型
`upath`	✅ 完全支持	✅ 通过 `.mjs` 或条件导出	✅ 内置
`upath2`	❌ 不支持	✅ 原生支持	✅ 内置（源码即 TS）
`path2`	✅（但已废弃）	❌	❌

实际影响示例

在 CommonJS 项目中（如传统 Node.js 脚本）：

// 只能用 upath
const upath = require('upath');
const filePath = upath.join(__dirname, 'assets', 'logo.png');

**在纯 ESM 项目中（package.json 设 `

如何选择: upath vs path2 vs upath2

upath:
选择 upath 如果你需要一个稳定、轻量且广泛采用的跨平台路径处理方案。它完全兼容原生 path 模块的 API，同时自动将所有路径转换为 POSIX 风格（正斜杠 /），有效规避 Windows 路径分隔符带来的问题。适用于大多数需要路径标准化但不依赖实验性功能的项目。
path2:
不建议在新项目中使用 path2。该包已被官方标记为废弃（deprecated），其 npm 页面明确指出“不再维护，请改用 upath”。尽管它曾试图提供比原生 path 更一致的行为，但缺乏持续更新意味着它可能无法兼容新版 Node.js 或修复已知问题。
upath2:
选择 upath2 如果你希望使用基于现代 JavaScript（ESM）构建的路径工具，并且项目已全面迁移到 ES 模块。它是 upath 的继任者，采用 TypeScript 编写，仅支持 ESM 导入，不提供 CommonJS 支持。适合新启动的、以 ESM 为标准的工具链项目。

与upath类似的npm包

upath 是一个用于处理文件路径的库，旨在提供跨平台的路径操作功能。它可以在 Node.js 和浏览器环境中使用，帮助开发者轻松地处理和转换路径。虽然 upath 提供了强大的路径处理能力，但在 JavaScript 生态系统中还有其他一些库可以作为替代方案。以下是一些替代库：

path 是 Node.js 内置的路径模块，提供了一系列用于处理和转换文件路径的实用函数。它支持绝对路径和相对路径的操作，并能够处理不同操作系统的路径分隔符。如果你只在 Node.js 环境中工作，使用内置的 path 模块是一个简单而有效的选择。
path-browserify 是一个为浏览器环境提供的路径模块，旨在模拟 Node.js 的 path 模块。它允许开发者在浏览器中以类似于 Node.js 的方式处理路径，适合需要在浏览器中进行路径操作的项目。如果你希望在浏览器中使用与 Node.js 相同的路径处理功能，path-browserify 是一个不错的选择。
path-to-regexp 是一个用于将路径字符串转换为正则表达式的库，常用于路由匹配。它允许开发者定义动态路径并从 URL 中提取参数。对于需要处理路由和 URL 匹配的应用程序，path-to-regexp 提供了强大的功能。
upath2 是 upath 的一个分支，旨在提供更好的功能和性能。它与 upath 类似，但可能在某些方面进行了优化。如果你正在寻找 upath 的替代品，upath2 可能是一个值得考虑的选项。

要查看这些库之间的比较，请访问：比较 path vs path-browserify vs path-to-regexp vs upath vs upath2。

与upath2类似的npm包

upath2 是一个用于处理文件路径的 Node.js 工具库，它是对原生 path 模块的增强版本，特别针对跨平台（尤其是 Windows 和 Unix 系统之间）路径格式的统一处理进行了优化。upath2 旨在解决路径分隔符不一致、大小写敏感性以及路径规范化等问题，使开发者能够编写更健壮、可移植的文件系统相关代码。

在 npm 生态中，还有其他类似的路径处理库可供选择：

path2 是另一个对 Node.js 原生 path 模块的封装或扩展，可能提供额外的实用方法或更现代的 API 设计。不过，该包的使用范围和社区支持相对有限，具体功能需参考其文档。
upath 是 upath2 的前身或早期版本，同样致力于统一不同操作系统的路径行为，尤其在将反斜杠（``）自动转换为正斜杠（/）方面表现突出。许多旧项目仍在使用 upath，而 upath2 则在其基础上进行了改进、修复或现代化重构。

要详细了解这三个包之间的差异，包括下载量、依赖关系、更新频率和功能对比，请查看：Comparing path2 vs upath vs upath2。

upath

path2

upath2

upath的README

upath v2.0.1

A drop-in replacement / proxy to nodejs's path that:

Replaces the windows \ with the unix / in all string params & results. This has significant positives - see below.
Adds filename extensions functions addExt, trimExt, removeExt, changeExt, and defaultExt.
Add a normalizeSafe function to preserve any meaningful leading ./ & a normalizeTrim which additionally trims any useless ending /.
Plus a helper toUnix that simply converts \ to / and consolidates duplicates.

Useful note: these docs are actually auto generated from specs, running on Linux.

Notes:

upath.sep is set to '/' for seamless replacement (as of 1.0.3).
upath has no runtime dependencies, except built-in path (as of 1.0.4)
travis-ci tested in node versions 8 to 14 (on linux)
Also tested on Windows / node@12.18.0 (without CI)

History brief:

1.x : Initial release and various features / fixes
2.0.0 : Adding UNC paths support - see https://github.com/anodynos/upath/pull/38

Why ?

Normal path doesn't convert paths to a unified format (ie /) before calculating paths (normalize, join), which can lead to numerous problems. Also path joining, normalization etc on the two formats is not consistent, depending on where it runs. Running path on Windows yields different results than when it runs on Linux / Mac.

In general, if you code your paths logic while developing on Unix/Mac and it runs on Windows, you may run into problems when using path.

Note that using Unix / on Windows works perfectly inside nodejs (and other languages), so there's no reason to stick to the Windows legacy at all.

Examples / specs

Check out the different (improved) behavior to vanilla path:

`upath.normalize(path)`        --returns-->

      ✓ `'c:/windows/nodejs/path'`         --->      `'c:/windows/nodejs/path'`  // equal to `path.normalize()`
      ✓ `'c:/windows/../nodejs/path'`      --->              `'c:/nodejs/path'`  // equal to `path.normalize()`
      ✓ `'c:\\windows\\nodejs\\path'`      --->      `'c:/windows/nodejs/path'`  // `path.normalize()` gives `'c:\windows\nodejs\path'`
      ✓ `'c:\\windows\\..\\nodejs\\path'`  --->              `'c:/nodejs/path'`  // `path.normalize()` gives `'c:\windows\..\nodejs\path'`
      ✓ `'/windows\\unix/mixed'`           --->         `'/windows/unix/mixed'`  // `path.normalize()` gives `'/windows\unix/mixed'`
      ✓ `'\\windows//unix/mixed'`          --->         `'/windows/unix/mixed'`  // `path.normalize()` gives `'\windows/unix/mixed'`
      ✓ `'\\windows\\..\\unix/mixed/'`     --->                `'/unix/mixed/'`  // `path.normalize()` gives `'\windows\..\unix/mixed/'`

Joining paths can also be a problem:

`upath.join(paths...)`        --returns-->

      ✓ `'some/nodejs/deep', '../path'`       --->       `'some/nodejs/path'`  // equal to `path.join()`
      ✓ `'some/nodejs\\windows', '../path'`   --->       `'some/nodejs/path'`  // `path.join()` gives `'some/path'`
      ✓ `'some\\windows\\only', '..\\path'`   --->      `'some/windows/path'`  // `path.join()` gives `'some\windows\only/..\path'`

Parsing with path.parse() should also be consistent across OSes:

upath.parse(path) --returns-->

      ✓ `'c:\Windows\Directory\somefile.ext'`      ---> `{ root: '', dir: 'c:/Windows/Directory', base: 'somefile.ext', ext: '.ext', name: 'somefile'

} //path.parse()gives'{ root: '', dir: '', base: 'c:\Windows\Directory\somefile.ext', ext: '.ext', name: 'c:\Windows\Directory\somefile' }' ✓'/root/of/unix/somefile.ext' --->{ root: '/', dir: '/root/of/unix', base: 'somefile.ext', ext: '.ext', name: 'somefile' } // equal topath.parse()`

Added functions

`upath.toUnix(path)`

Just converts all `` to / and consolidates duplicates, without performing any normalization.

Examples / specs

`upath.toUnix(path)`        --returns-->

    ✓ `'.//windows\//unix//mixed////'`      --->         `'./windows/unix/mixed/'`
    ✓ `'..///windows\..\\unix/mixed'`       --->      `'../windows/../unix/mixed'`

`upath.normalizeSafe(path)`

Exactly like path.normalize(path), but it keeps the first meaningful ./ or //.

Note that the unix / is returned everywhere, so windows \ is always converted to unix /.

Examples / specs & how it differs from vanilla `path`

`upath.normalizeSafe(path)`        --returns-->

    ✓ `''`                               --->                              `'.'`  // equal to `path.normalize()`
    ✓ `'.'`                              --->                              `'.'`  // equal to `path.normalize()`
    ✓ `'./'`                             --->                             `'./'`  // equal to `path.normalize()`
    ✓ `'.//'`                            --->                             `'./'`  // equal to `path.normalize()`
    ✓ `'.\\'`                            --->                             `'./'`  // `path.normalize()` gives `'.\'`
    ✓ `'.\\//'`                          --->                             `'./'`  // `path.normalize()` gives `'.\/'`
    ✓ `'./..'`                           --->                             `'..'`  // equal to `path.normalize()`
    ✓ `'.//..'`                          --->                             `'..'`  // equal to `path.normalize()`
    ✓ `'./../'`                          --->                            `'../'`  // equal to `path.normalize()`
    ✓ `'.\\..\\'`                        --->                            `'../'`  // `path.normalize()` gives `'.\..\'`
    ✓ `'./../dep'`                       --->                         `'../dep'`  // equal to `path.normalize()`
    ✓ `'../dep'`                         --->                         `'../dep'`  // equal to `path.normalize()`
    ✓ `'../path/dep'`                    --->                    `'../path/dep'`  // equal to `path.normalize()`
    ✓ `'../path/../dep'`                 --->                         `'../dep'`  // equal to `path.normalize()`
    ✓ `'dep'`                            --->                            `'dep'`  // equal to `path.normalize()`
    ✓ `'path//dep'`                      --->                       `'path/dep'`  // equal to `path.normalize()`
    ✓ `'./dep'`                          --->                          `'./dep'`  // `path.normalize()` gives `'dep'`
    ✓ `'./path/dep'`                     --->                     `'./path/dep'`  // `path.normalize()` gives `'path/dep'`
    ✓ `'./path/../dep'`                  --->                          `'./dep'`  // `path.normalize()` gives `'dep'`
    ✓ `'.//windows\\unix/mixed/'`        --->          `'./windows/unix/mixed/'`  // `path.normalize()` gives `'windows\unix/mixed/'`
    ✓ `'..//windows\\unix/mixed'`        --->          `'../windows/unix/mixed'`  // `path.normalize()` gives `'../windows\unix/mixed'`
    ✓ `'windows\\unix/mixed/'`           --->            `'windows/unix/mixed/'`  // `path.normalize()` gives `'windows\unix/mixed/'`
    ✓ `'..//windows\\..\\unix/mixed'`    --->                  `'../unix/mixed'`  // `path.normalize()` gives `'../windows\..\unix/mixed'`
    ✓ `'\\\\server\\share\\file'`        --->            `'//server/share/file'`  // `path.normalize()` gives `'\\server\share\file'`
    ✓ `'//server/share/file'`            --->            `'//server/share/file'`  // `path.normalize()` gives `'/server/share/file'`
    ✓ `'\\\\?\\UNC\\server\\share\\file'` --->      `'//?/UNC/server/share/file'`  // `path.normalize()` gives `'\\?\UNC\server\share\file'`
    ✓ `'\\\\LOCALHOST\\c$\\temp\\file'`  --->       `'//LOCALHOST/c$/temp/file'`  // `path.normalize()` gives `'\\LOCALHOST\c$\temp\file'`
    ✓ `'\\\\?\\c:\\temp\\file'`          --->               `'//?/c:/temp/file'`  // `path.normalize()` gives `'\\?\c:\temp\file'`
    ✓ `'\\\\.\\c:\\temp\\file'`          --->               `'//./c:/temp/file'`  // `path.normalize()` gives `'\\.\c:\temp\file'`
    ✓ `'//./c:/temp/file'`               --->               `'//./c:/temp/file'`  // `path.normalize()` gives `'/c:/temp/file'`
    ✓ `'////\\.\\c:/temp\\//file'`       --->               `'//./c:/temp/file'`  // `path.normalize()` gives `'/\.\c:/temp\/file'`

`upath.normalizeTrim(path)`

Exactly like path.normalizeSafe(path), but it trims any useless ending /.

Examples / specs

`upath.normalizeTrim(path)`        --returns-->

    ✓ `'./'`                          --->                         `'.'`  // `upath.normalizeSafe()` gives `'./'`
    ✓ `'./../'`                       --->                        `'..'`  // `upath.normalizeSafe()` gives `'../'`
    ✓ `'./../dep/'`                   --->                    `'../dep'`  // `upath.normalizeSafe()` gives `'../dep/'`
    ✓ `'path//dep\\'`                 --->                  `'path/dep'`  // `upath.normalizeSafe()` gives `'path/dep/'`
    ✓ `'.//windows\\unix/mixed/'`     --->      `'./windows/unix/mixed'`  // `upath.normalizeSafe()` gives `'./windows/unix/mixed/'`

`upath.joinSafe([path1][, path2][, ...])`

Exactly like path.join(), but it keeps the first meaningful ./ or //.

Note that the unix / is returned everywhere, so windows \ is always converted to unix /.

Examples / specs & how it differs from vanilla `path`

`upath.joinSafe(path)`        --returns-->

    ✓ `'some/nodejs/deep', '../path'`                --->           `'some/nodejs/path'`  // equal to `path.join()`
    ✓ `'./some/local/unix/', '../path'`              --->          `'./some/local/path'`  // `path.join()` gives `'some/local/path'`
    ✓ `'./some\\current\\mixed', '..\\path'`         --->        `'./some/current/path'`  // `path.join()` gives `'some\current\mixed/..\path'`
    ✓ `'../some/relative/destination', '..\\path'`   --->      `'../some/relative/path'`  // `path.join()` gives `'../some/relative/destination/..\path'`
    ✓ `'\\\\server\\share\\file', '..\\path'`        --->        `'//server/share/path'`  // `path.join()` gives `'\\server\share\file/..\path'`
    ✓ `'\\\\.\\c:\\temp\\file', '..\\path'`          --->           `'//./c:/temp/path'`  // `path.join()` gives `'\\.\c:\temp\file/..\path'`
    ✓ `'//server/share/file', '../path'`             --->        `'//server/share/path'`  // `path.join()` gives `'/server/share/path'`
    ✓ `'//./c:/temp/file', '../path'`                --->           `'//./c:/temp/path'`  // `path.join()` gives `'/c:/temp/path'`

Added functions for filename extension manipulation.

Happy notes:

In all functions you can:

use both .ext & ext - the dot . on the extension is always adjusted correctly.
omit the ext param (pass null/undefined/empty string) and the common sense thing will happen.
ignore specific extensions from being considered as valid ones (eg .min, .dev .aLongExtIsNotAnExt etc), hence no trimming or replacement takes place on them.

`upath.addExt(filename, [ext])`

Adds .ext to filename, but only if it doesn't already have the exact extension.

Examples / specs

`upath.addExt(filename, 'js')`     --returns-->

    ✓ `'myfile/addExt'`           --->           `'myfile/addExt.js'`
    ✓ `'myfile/addExt.txt'`       --->       `'myfile/addExt.txt.js'`
    ✓ `'myfile/addExt.js'`        --->           `'myfile/addExt.js'`
    ✓ `'myfile/addExt.min.'`      --->      `'myfile/addExt.min..js'`

It adds nothing if no ext param is passed.

`upath.addExt(filename)`           --returns-->

      ✓ `'myfile/addExt'`           --->              `'myfile/addExt'`
      ✓ `'myfile/addExt.txt'`       --->          `'myfile/addExt.txt'`
      ✓ `'myfile/addExt.js'`        --->           `'myfile/addExt.js'`
      ✓ `'myfile/addExt.min.'`      --->         `'myfile/addExt.min.'`

`upath.trimExt(filename, [ignoreExts], [maxSize=7])`

Trims a filename's extension.

Extensions are considered to be up to maxSize chars long, counting the dot (defaults to 7).
An Array of ignoreExts (eg ['.min']) prevents these from being considered as extension, thus are not trimmed.

Examples / specs

`upath.trimExt(filename)`          --returns-->

    ✓ `'my/trimedExt.txt'`             --->                 `'my/trimedExt'`
    ✓ `'my/trimedExt'`                 --->                 `'my/trimedExt'`
    ✓ `'my/trimedExt.min'`             --->                 `'my/trimedExt'`
    ✓ `'my/trimedExt.min.js'`          --->             `'my/trimedExt.min'`
    ✓ `'../my/trimedExt.longExt'`      --->      `'../my/trimedExt.longExt'`

It is ignoring .min & .dev as extensions, and considers exts with up to 8 chars.

`upath.trimExt(filename, ['min', '.dev'], 8)`          --returns-->

      ✓ `'my/trimedExt.txt'`              --->                  `'my/trimedExt'`
      ✓ `'my/trimedExt.min'`              --->              `'my/trimedExt.min'`
      ✓ `'my/trimedExt.dev'`              --->              `'my/trimedExt.dev'`
      ✓ `'../my/trimedExt.longExt'`       --->               `'../my/trimedExt'`
      ✓ `'../my/trimedExt.longRExt'`      --->      `'../my/trimedExt.longRExt'`

`upath.removeExt(filename, ext)`

Removes the specific ext extension from filename, if it has it. Otherwise it leaves it as is. As in all upath functions, it be .ext or ext.

Examples / specs

`upath.removeExt(filename, '.js')`          --returns-->

    ✓ `'removedExt.js'`          --->          `'removedExt'`
    ✓ `'removedExt.txt.js'`      --->      `'removedExt.txt'`
    ✓ `'notRemoved.txt'`         --->      `'notRemoved.txt'`

It does not care about the length of exts.

`upath.removeExt(filename, '.longExt')`          --returns-->

    ✓ `'removedExt.longExt'`          --->          `'removedExt'`
    ✓ `'removedExt.txt.longExt'`      --->      `'removedExt.txt'`
    ✓ `'notRemoved.txt'`              --->      `'notRemoved.txt'`

`upath.changeExt(filename, [ext], [ignoreExts], [maxSize=7])`

Changes a filename's extension to ext. If it has no (valid) extension, it adds it.

Valid extensions are considered to be up to maxSize chars long, counting the dot (defaults to 7).
An Array of ignoreExts (eg ['.min']) prevents these from being considered as extension, thus are not changed - the new extension is added instead.

Examples / specs

`upath.changeExt(filename, '.js')`  --returns-->

    ✓ `'my/module.min'`            --->                `'my/module.js'`
    ✓ `'my/module.coffee'`         --->                `'my/module.js'`
    ✓ `'my/module'`                --->                `'my/module.js'`
    ✓ `'file/withDot.'`            --->             `'file/withDot.js'`
    ✓ `'file/change.longExt'`      --->      `'file/change.longExt.js'`

If no ext param is given, it trims the current extension (if any).

`upath.changeExt(filename)`        --returns-->

      ✓ `'my/module.min'`            --->                   `'my/module'`
      ✓ `'my/module.coffee'`         --->                   `'my/module'`
      ✓ `'my/module'`                --->                   `'my/module'`
      ✓ `'file/withDot.'`            --->                `'file/withDot'`
      ✓ `'file/change.longExt'`      --->         `'file/change.longExt'`

It is ignoring .min & .dev as extensions, and considers exts with up to 8 chars.

`upath.changeExt(filename, 'js', ['min', '.dev'], 8)`        --returns-->

      ✓ `'my/module.coffee'`          --->                 `'my/module.js'`
      ✓ `'file/notValidExt.min'`      --->      `'file/notValidExt.min.js'`
      ✓ `'file/notValidExt.dev'`      --->      `'file/notValidExt.dev.js'`
      ✓ `'file/change.longExt'`       --->               `'file/change.js'`
      ✓ `'file/change.longRExt'`      --->      `'file/change.longRExt.js'`

`upath.defaultExt(filename, [ext], [ignoreExts], [maxSize=7])`

Adds .ext to filename, only if it doesn't already have any old extension.

(Old) extensions are considered to be up to maxSize chars long, counting the dot (defaults to 7).
An Array of ignoreExts (eg ['.min']) will force adding default .ext even if one of these is present.

Examples / specs

`upath.defaultExt(filename, 'js')`   --returns-->

    ✓ `'fileWith/defaultExt'`              --->              `'fileWith/defaultExt.js'`
    ✓ `'fileWith/defaultExt.js'`           --->              `'fileWith/defaultExt.js'`
    ✓ `'fileWith/defaultExt.min'`          --->             `'fileWith/defaultExt.min'`
    ✓ `'fileWith/defaultExt.longExt'`      --->      `'fileWith/defaultExt.longExt.js'`

If no ext param is passed, it leaves filename intact.

`upath.defaultExt(filename)`       --returns-->

      ✓ `'fileWith/defaultExt'`              --->                 `'fileWith/defaultExt'`
      ✓ `'fileWith/defaultExt.js'`           --->              `'fileWith/defaultExt.js'`
      ✓ `'fileWith/defaultExt.min'`          --->             `'fileWith/defaultExt.min'`
      ✓ `'fileWith/defaultExt.longExt'`      --->         `'fileWith/defaultExt.longExt'`

It is ignoring .min & .dev as extensions, and considers exts with up to 8 chars.

`upath.defaultExt(filename, 'js', ['min', '.dev'], 8)` --returns-->

      ✓ `'fileWith/defaultExt'`               --->               `'fileWith/defaultExt.js'`
      ✓ `'fileWith/defaultExt.min'`           --->           `'fileWith/defaultExt.min.js'`
      ✓ `'fileWith/defaultExt.dev'`           --->           `'fileWith/defaultExt.dev.js'`
      ✓ `'fileWith/defaultExt.longExt'`       --->          `'fileWith/defaultExt.longExt'`
      ✓ `'fileWith/defaultExt.longRext'`      --->      `'fileWith/defaultExt.longRext.js'`

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

跨平台路径处理库的技术选型

npm下载趋势

GitHub Stars 排名

统计详情

跨平台路径处理：path2、upath 与 upath2 深度对比

⚠️ 维护状态：先看是否还能用

🔧 核心功能：API 兼容性与路径标准化

原生 path 的问题示例

upath：强制统一为 POSIX 风格

upath2：同样标准化，但仅支持 ESM

path2（已废弃）：历史行为

📦 模块系统支持：CommonJS 还是 ESM？

实际影响示例

如何选择: upath vs path2 vs upath2

热门对比

与upath类似的npm包

与upath2类似的npm包

upath的README

upath v2.0.1

Why ?

Examples / specs

Added functions

upath.toUnix(path)

Examples / specs

upath.normalizeSafe(path)

Examples / specs & how it differs from vanilla path

upath.normalizeTrim(path)

Examples / specs

upath.joinSafe([path1][, path2][, ...])

Examples / specs & how it differs from vanilla path

Added functions for filename extension manipulation.

upath.addExt(filename, [ext])

Examples / specs

upath.trimExt(filename, [ignoreExts], [maxSize=7])

Examples / specs

upath.removeExt(filename, ext)

Examples / specs

upath.changeExt(filename, [ext], [ignoreExts], [maxSize=7])

Examples / specs

upath.defaultExt(filename, [ext], [ignoreExts], [maxSize=7])

Examples / specs

原生 `path` 的问题示例

`upath`：强制统一为 POSIX 风格

`upath2`：同样标准化，但仅支持 ESM

`path2`（已废弃）：历史行为

`upath.toUnix(path)`

`upath.normalizeSafe(path)`

Examples / specs & how it differs from vanilla `path`

`upath.normalizeTrim(path)`

`upath.joinSafe([path1][, path2][, ...])`

Examples / specs & how it differs from vanilla `path`

`upath.addExt(filename, [ext])`

`upath.trimExt(filename, [ignoreExts], [maxSize=7])`

`upath.removeExt(filename, ext)`

`upath.changeExt(filename, [ext], [ignoreExts], [maxSize=7])`

`upath.defaultExt(filename, [ext], [ignoreExts], [maxSize=7])`