slugify
`sindresorhus/slugify` 可将多语言字符串转写为适合网址、文件名和标识使用的安全短标识,并支持自定义转换规则与分隔符。
项目信息
文章目录
这是什么
sindresorhus/slugify 是一个把普通字符串整理成 slug 的开源工具。这里的 slug 不是随机哈希,而是保留可读语义、适合放入网址、文件名和标识中的文本。默认情况下,它会统一小写、使用连字符分隔单词,并清理符号、空格和多余分隔符,例如把 Déjà Vu! 变成 deja-vu,把 fooBar 123 $#% 变成 foo-bar-123。
它的价值不只是“去掉特殊字符”。项目支持德语变音符号、越南语、阿拉伯语、俄语等主要语言,并可通过 locale 选择语言相关的转写结果。瑞典语 Räksmörgås 在指定 locale: 'sv' 后可得到 raksmorgas。驼峰命名也会被拆成独立单词,让变量名、业务标题和文章标题更易读。
该项目主要使用 JavaScript,采用 MIT 许可证,最新版本为 v3.0.2,在 GitHub 上获得 2710 个 Star。其流程可以概括为“先转写,再清理,最后输出”:Unicode 内容先转换为可接受的字符,再由选项控制大小写、分隔符和保留规则,适合作为 URL 路由、文章锚点、对象 ID 或文件名生成流程中的基础工具。仓库地址为 https://github.com/sindresorhus/slugify。
适合谁用
适合需要在 Node.js 或其他 JavaScript 环境中处理 slug 的开发者。后台收到带空格、中文或标点的标题,需要生成 URL 片段;文档系统需要把章节标题转换为锚点;业务代码希望把名称整理成便于复制和传递的标识,都可以把它作为统一的前置步骤。
如果项目需要保留驼峰原貌、下划线开头、结尾短横线或某个 URL 片段字符,也有对应开关。对于重复标题,可用带计数器的实例生成 foo-bar、foo-bar-2,让同一文档中的多个小节拥有不同锚点。
亮点
- 多语言转写:支持德语变音符号、越南语、阿拉伯语和俄语等,并可按 locale 调整。
- 默认结果易读:自动小写、拆分驼峰,并以连字符连接单词。
- 输出规则可配置:separator、lowercase、decamelize 和 transliterate 可分别调整。
- 特殊语义可保留:可保留下划线开头、结尾短横线及指定字符。
- 重复值有计数器:slugifyWithCounter 可为重复结果追加序号并重置。
怎么用
先通过 npm 安装这个包:
npm install @sindresorhus/slugify
安装后,在使用 ES Module 的 JavaScript 项目中导入默认函数即可。slugify() 接收字符串和可选配置,返回处理后的字符串:
import slugify from '@sindresorhus/slugify';
slugify('I ♥ Dogs');
//=> 'i-love-dogs'
slugify(' Déjà Vu! ');
//=> 'deja-vu'
slugify('я люблю единорогов');
//=> 'ya-lyublyu-edinorogov'
slugify('fooBar', {decamelize: false});
//=> 'foobar'
基础调用会使用默认配置。需要自定义时,可通过 separator 改用下划线或取消分隔符,通过 lowercase 控制大小写,通过 decamelize 决定是否拆分驼峰。customReplacements 会在其他转换前执行,默认包含 &、🦄 和 ♥ 的替换;传入相同键即可覆盖默认项,替换值两侧的空格会影响最终分隔符。
slugify('BAR and baz', {separator: '_'});
//=> 'bar_and_baz'
slugify('Déjà Vu!', {lowercase: false});
//=> 'Déjà-Vu'
slugify('Foo@unicorn', {
customReplacements: [
['@', ' at ']
]
});
//=> 'foo-at-unicorn'
转写层面,locale 可以选择特定语言的规则;关闭 transliterate 后,非 ASCII 字符会直接保留。对于有特殊含义的边界字符,还可以选择保留下划线开头、结尾短横线,以及不能与分隔符重复的指定字符。
slugify('Räksmörgås', {locale: 'sv'});
//=> 'raksmorgas'
slugify('Déjà Vu', {transliterate: false});
//=> 'déjà-vu'
slugify('_foo_bar', {preserveLeadingUnderscore: true});
//=> '_foo-bar'
slugify('foo-bar-', {preserveTrailingDash: true});
//=> 'foo-bar-'
slugify('foo_bar#baz', {preserveCharacters: ['#']});
//=> 'foo-bar#baz'
如果同一份文档中存在重复标题,可以使用 slugifyWithCounter() 创建带计数的新实例。实例会为重复结果追加序号,调用 reset() 后重新开始计数。
import {slugifyWithCounter} from '@sindresorhus/slugify';
const uniqueSlug = slugifyWithCounter();
uniqueSlug('foo bar');
//=> 'foo-bar'
uniqueSlug('foo bar');
//=> 'foo-bar-2'
uniqueSlug.reset();
uniqueSlug('foo bar');
//=> 'foo-bar'
注意事项
customReplacements会在其他转换之前执行,相同键会覆盖默认替换;替换值两侧是否留空格也会影响最终分隔符。preserveCharacters不能包含separator,而且即使保留撇号,词尾的's或't仍会被删除。- 该项目解决的是可读 slug 生成,不等同于通用安全过滤或严格的文件系统文件名校验。若必须得到合法且安全的文件名,可关注仓库列出的
filenamify;带计数器的实例则应在其自身生命周期内使用,并在需要时调用reset()。
国内镜像下载
这个项目已经镜像到站长自己的服务器,GitHub 打不开、或者下载太慢的时候,直接从这里拿。
项目与资料
整理自本文的外部链接,请以来源页面说明为准。