Changesets项目中自定义TypeScript变更日志格式化器的实践指南

背景介绍

Changesets是一个流行的版本控制和变更日志管理工具，它允许开发者通过自定义格式化器来灵活控制变更日志的输出格式。虽然官方文档提供了相关指引，但在实际使用TypeScript实现自定义格式化器时，开发者可能会遇到一些技术挑战。

核心问题分析

当开发者尝试按照官方文档使用TypeScript编写自定义变更日志格式化器时，通常会遇到"Cannot use import statement outside a module"的错误。这是因为Changesets默认不会处理TypeScript文件的转译工作，它期望直接加载可执行的JavaScript代码。

解决方案

方案一：使用JSDoc注释的JavaScript文件

对于希望保留类型检查功能但不想处理转译复杂性的开发者，可以采用纯JavaScript文件配合JSDoc注释的方式：

/** @type {import('@changesets/types').GetReleaseLine} */
async function getReleaseLine(changesets, type, changelogOpts) {
  const [firstLine, ...futureLines] = changeset.summary
    .split("\n")
    .map((l) => l.trimEnd());
  return `- ${firstLine}` + 
    (futureLines.length > 0 
      ? `\n${futureLines.map((l) => `  ${l}`).join("\n")}` 
      : "");
}
 
/** @type {import('@changesets/types').GetDependencyReleaseLine} */
async function getDependencyReleaseLine(changesets, dependenciesUpdated) {
  // 实现依赖项的变更日志行
}

module.exports = {
  getReleaseLine,
  getDependencyReleaseLine
};

这种方法既保持了类型安全，又避免了转译的复杂性。

方案二：通过中间文件代理TypeScript模块

对于坚持使用TypeScript的开发者，可以创建一个代理文件来处理转译：

1. 首先安装必要的依赖：

npm install tsx --save-dev

2. 创建代理文件changelog-proxy.js：

require("tsx/cjs");
module.exports = require("./changelog-formatter.ts");

3. 在配置中引用代理文件：

{
  "changelog": "./changelog-proxy.js"
}

技术原理深入

Changesets作为一个版本管理工具，其核心设计理念是保持轻量化和专注。它不内置TypeScript转译功能是经过深思熟虑的设计决策：

1. 依赖最小化：避免引入额外的转译工具链依赖
2. 性能考量：转译会增加版本发布过程的时间
3. 维护成本：支持多种转译工具会增加项目的维护负担

最佳实践建议

1. 简单场景：对于大多数项目，使用JSDoc注释的JavaScript方案已经足够
2. 复杂场景：当变更日志逻辑非常复杂时，才考虑TypeScript方案
3. 团队协作：确保所有团队成员了解所使用的方案，并在文档中明确说明
4. 构建流程：如果项目已有构建流程，可以考虑将格式化器纳入其中

总结

Changesets提供了灵活的变更日志定制能力，虽然不直接支持TypeScript格式化器，但通过本文介绍的两种方案，开发者可以既享受TypeScript的类型安全，又能顺利集成到Changesets工作流中。理解工具的设计哲学和限制条件，有助于我们做出更合理的技术选型和实现方案。