从 Lodash lowerFirst 迁移到 Remeda uncapitalize：首字母小写的正确姿势
从 Lodash lowerFirst 迁移到 Remeda uncapitalize：首字母小写的正确姿势
本文讲解如何在 Remeda 中完成 Lodash lowerFirst（将字符串首字母转为小写）的等价迁移，核心对应函数为 Remeda 的 uncapitalize。文章基于 remeda 仓库文档站的官方迁移映射文档（lowerFirst.md）展开，并结合 uncapitalize.ts 源码及其测试用例，梳理两条函数的行为差异、缺失输入处理方案、纯展示场景的 CSS 替代方案，以及相关的字符串大小写工具族，帮助你写出行为等价、类型安全的迁移代码。
一、映射速览：lowerFirst → uncapitalize
在 remeda 仓库的文档站中，迁移映射文档通过 frontmatter 声明两条函数的关系：
category: String
remeda: uncapitalize
即 Lodash 的 lowerFirst 归类在 String（字符串处理）类别下，对应 Remeda 的 uncapitalize。基本用法完全对齐：
// Lodash
_.lowerFirst(input);
// Remeda
uncapitalize(input);
语义一致：只把字符串的第一个字符转为小写，其余字符保持原样。例如：
uncapitalize("HELLO WORLD"); // "hELLO WORLD"
uncapitalize("HeLlO WoRlD"); // "heLlO WoRlD"
uncapitalize("hello world"); // "hello world"（首字符本来就是小写，原样返回）
二、关键差异：Lodash 允许无参调用，Remeda 严格要求字符串
这是迁移时最容易踩坑的行为差异，映射文档特别指出了这一点：
Lodash allows calling
lowerFirstwithout any input (or with anundefinedinput), which results in an empty string"". Remeda'suncapitalizerequires a string input.
具体表现为：
_.lowerFirst()返回""（空字符串）；_.lowerFirst(undefined)同样返回""；- Remeda 的
uncapitalize不接受undefined或缺失参数，签名要求传入一个data: T extends string的字符串。
从源码可以确认这一点：uncapitalize.ts 的 data-first 签名是 uncapitalize<T extends string>(data: T): Uncapitalize<T>，没有提供可省略参数的变体；且函数体内部不做 undefined 兜底。因此，从 Lodash 迁移过来时，必须先处理好输入可能缺失的情况（详见第五节）。
三、uncapitalize 的实现原理：只动首字符，其余原样保留
阅读 uncapitalize.ts 的源码，其核心实现只有一行：
const uncapitalizeImplementation = <T extends string>(
data: T,
): Uncapitalize<T> =>
`${data[0]?.toLowerCase() ?? ""}${data.slice(1)}` as Uncapitalize<T>;
拆解这行代码可以看到几个关键设计：
data[0]?.toLowerCase()：取第一个字符并转为小写。注意这里用了可选链：当字符串为空时data[0]是undefined，此时?.toLowerCase()不会报错；?? ""：当首字符不存在（空字符串）时，用空字符串占位。因此uncapitalize("")返回""，与 Lodash 对空串的行为一致，测试用例 uncapitalize.test.ts 中也有明确断言；${data.slice(1)}：从第二个字符开始原样拼接，不改变其余字符的大小写。这正是lowerFirst与"全小写"类函数的本质区别——它只影响首字母；- 类型层面：返回值类型是 TypeScript 内置的模板字面量工具类型
Uncapitalize<T>，能够在编译期推断出精确的字符串字面量类型，而非宽泛的string。
此外，源码注释明确指出：运行时依赖 String.prototype.toLowerCase，类型层依赖 Uncapitalize 工具类型，因此两者共享 toLowerCase 的 locale 不准确性——对于依赖区域语言规则的场景（如土耳其语的特殊大小写规则），uncapitalize 不会自动适配 locale；如需更符合语言学的转换，应使用原生 toLocaleLowerCase，或直接采用第五节介绍的 CSS 方案。
空字符串与代理对边界：测试用例给出的保证
uncapitalize.test.ts 的测试覆盖了值得关注的边界情况：
- 空字符串返回
""； - 全大写、全小写、混合大小写均只处理首字符；
- 非拉丁文字：
uncapitalize("Москва")→"москва"，uncapitalize("Ελλάδα")→"ελλάδα"； - 变音符号：
uncapitalize("Café Naïve")→"café Naïve"，重音字符只对首字符生效，不影响其余字符； - 代理对（astral plane）：
uncapitalize("𝒽Ello World")→"𝒽Ello World"，注意这里"首字符"按 JavaScript 的 UTF-16 code unit 索引取的是data[0]，而𝒽是双 code unit 的字符，其首个 code unit 转小写后保持不变，因此结果不被破坏； - emoji：
uncapitalize("🎉Party Time")→"🎉Party Time"，emoji 不会被误伤； - 组合字符：
uncapitalize("É\u{301}llo")→"é\u{301}llo"。
这些用例证明：即使面对复杂 Unicode 输入，uncapitalize 也能保证"不改坏其余部分、不抛异常"的稳定行为。
四、data-first 与 data-last：在管道中使用 uncapitalize
与 Remeda 中大多数函数一样，uncapitalize 通过 purry 机制提供两种调用签名（见 purry.ts 中的 purry(uncapitalizeImplementation, args) 调用）。在 uncapitalize.ts 中声明了 data-last 版本：
export function uncapitalize(): <T extends string>(data: T) => Uncapitalize<T>;
因此既可以直接调用，也可以在 pipe 管道中作为数据居后的函数使用：
// data-first
uncapitalize("HELLO WORLD"); // "hELLO WORLD"
// data-last，配合管道
pipe("HELLO WORLD", uncapitalize()); // "hELLO WORLD"
在管道中，uncapitalize() 返回一个等待接收字符串的函数，适合与其他字符串处理步骤串联。这一双签名模式与仓库内其他 String 类函数（如 capitalize、toLowerCase）完全一致。
五、缺失输入的处理：三种写法，一个原则
由于 Lodash 允许无参调用，迁移时如果数据源可能产生 undefined，映射文档给出了两种等价的 Remeda 写法：
// 方案一：显式判空
input !== undefined ? uncapitalize(input) : "";
// 方案二：空值合并
uncapitalize(input ?? "");
两种方案的结果都与 _.lowerFirst() / _.lowerFirst(undefined) 返回 "" 的行为一致。方案二更简洁，推荐在代码中直接使用；方案一则适合在需要区分"输入缺失"与"输入为空字符串"的业务场景中保留显式分支。
值得注意的是，如果输入类型是 string | undefined，方案二还能让 TypeScript 收窄类型，从而顺利通过 uncapitalize 的 T extends string 参数约束，编译期即可避免类型错误。
六、纯展示场景：优先使用 CSS 而非 JS 转换
映射文档反复强调一个最佳实践：如果字符串大小写只是用于页面展示，不要用 JS 函数做运行时转换，而应交给 CSS。lowerFirst 对应的 CSS 方案是：
// Lodash
<div>{_.lowerFirst(input)}</div>
// CSS
<style>
.lowerFirst::first-letter {
text-transform: lowercase;
}
</style>
<div class="lowerFirst">{input}</div>
这一建议的理由充分：
- locale-aware：CSS 的
text-transform是感知区域语言的，而uncapitalize底层依赖的toLowerCase存在 locale 不准确性（源码注释已明确说明）； - 零运行时开销：样式处理不需要生成新的字符串，避免了不必要的 JS 计算与重新渲染；
- 更符合语义：展示层的大小写属于"呈现"而非"数据"，用 CSS 表达后，原始数据保持原样，可检索性更好。
同理，映射文档站中其他字符串函数（如 capitalize、upperFirst、toLower）也给出了对应的 CSS 替代模式，可见"展示优先用 CSS"是 Remeda 官方迁移建议的一致原则。
七、更完整的迁移上下文：字符串大小写工具族
uncapitalize 不是孤立存在的。其源码注释（uncapitalize.ts）列出了同类的其他大小写处理函数：toUpperCase、toLowerCase、capitalize、toCamelCase、toKebabCase、toSnakeCase、toTitleCase。理解它们之间的关系有助于选对迁移目标：
| Lodash 函数 | Remeda 对应 | 行为说明 |
|---|---|---|
lowerFirst |
uncapitalize |
仅首字符转小写，其余原样 |
upperFirst |
capitalize |
仅首字符转大写，其余原样（见 upperFirst.md） |
toLower |
toLowerCase |
全部字符转小写 |
toUpper |
toUpperCase |
全部字符转大写 |
capitalize |
capitalize + toLowerCase 组合 |
注意：Lodash 的 capitalize 会先将整个字符串转小写再大写首字符，与 Remeda 的 capitalize 语义不同（详见 capitalize.md） |
其中最容易混淆的是 capitalize：Lodash 的 _.capitalize("hELLO") 结果是 "Hello"（先全小写再大写首字符），而 Remeda 的 capitalize("hELLO") 结果是 "HeLLO"（只动首字符）。要在 Remeda 中复现 Lodash 的 capitalize 语义，需要组合调用：
// 等价于 Lodash _.capitalize(input)
capitalize(toLowerCase(input));
理解这条差异，才能避免在迁移 lowerFirst / upperFirst 附近的其他 Lodash 字符串 API 时踩坑。而 uncapitalize 由于语义与 lowerFirst 完全对齐，迁移时无需额外组合，直接替换即可。
八、这份映射文档在文档站中如何被消费
如果你在 remeda 仓库中想深入了解这套迁移映射的组织方式，可以顺着以下路径追踪：
- 映射内容定义在 packages/docs/src/content/mapping 目录，按库分子目录（
lodash/、ramda/、just/），每个函数一个 Markdown 文件，文件名即 Lodash 函数名； - 集合 schema 定义在 mapping/content.config.ts：要求
category非空，remeda字段是对 Remeda 函数文档的引用，并开启strict校验； - 迁移页面在 migrate/[library].astro](packages/docs/src/pages/migrate/%5Blibrary%5D.astro) 中生成，通过 [mapping/entries.ts 的
getMigrationMappings按 category 分组渲染； - 每张映射卡片由 mapping-function-card.astro 渲染，会展示对应的 Remeda 函数名并链接到其官方文档（
uncapitalize从 index.ts 导出）。
这套结构说明：lowerFirst → uncapitalize 的映射不只是文档站的"提示"，它与 Remeda 的真实实现、类型定义和测试用例一一对应，可以直接作为可信的迁移依据。
总结
从 Lodash lowerFirst 迁移到 Remeda uncapitalize 只需记住三件事：基本场景直接替换（_.lowerFirst(input) → uncapitalize(input)）；输入可能缺失时先兜底（推荐 uncapitalize(input ?? "")）；纯展示场景改用 CSS 的 ::first-letter + text-transform: lowercase。同时留意 uncapitalize 底层依赖 toLowerCase 的 locale 局限，并区分 capitalize 在两条库中的语义差异，即可稳妥完成迁移。仓库中 lowerFirst.md 提供了最精简的官方对照，而 uncapitalize.ts 与 uncapitalize.test.ts 则给出了最可靠的实现与边界行为证据。