在本指南中，我们将经历发布一个包到npm所需的每一个步骤。
这不是一个极简指南。我们将从一个空目录开始设置一个完全生产就绪的包。这将包括：
- Git 用于版本控制
- TypeScript 用于编写我们的代码并保持类型安全
- Prettier 用于格式化我们的代码
- @arethetypeswrong/cli 用于检查我们的导出
- tsup 用于将我们的TypeScript代码编译成CJS和ESM
- Vitest 用于运行我们的测试
- GitHub Actions 用于运行我们的CI流程
- Changesets 用于版本控制和发布我们的包
如果你想看到成品，请查看这个演示仓库。
1. Git
在本节中，我们将创建一个新的git仓库，设置一个.gitignore，创建初始提交，创建GitHub上的新仓库，并将我们的代码推送到GitHub。
1.1：初始化仓库
运行以下命令以初始化一个新的git仓库：
git init
1.2：设置.gitignore
在项目的根目录创建一个.gitignore文件，并添加以下内容：
node_modules
1.3：创建初始提交
运行以下命令以创建初始提交：
git add .
git commit -m "Initial commit"
1.4：在GitHub上创建新仓库
使用GitHub CLI，运行以下命令创建一个新的仓库。在这个例子中，我选择了tt-package-demo这个名字：
gh repo create tt-package-demo --source=. --public
1.5：推送到GitHub
运行以下命令将你的代码推送到GitHub：
git push --set-upstream origin main
2: package.json
在本节中，我们将创建一个package.json文件，添加一个license字段，创建一个LICENSE文件，并添加一个README.md文件。
2.1：创建一个package.json文件
创建一个包含这些值的package.json文件：
{
"name": "tt-package-demo",
"version": "1.0.0",
"description": "A demo package for Total TypeScript",
"keywords": ["demo", "typescript"],
"homepage": "https://github.com/mattpocock/tt-package-demo",
"bugs": {
"url": "https://github.com/mattpocock/tt-package-demo/issues"
},
"author": "Matt Pocock <team@totaltypescript.com> (https://totaltypescript.com)",
"repository": {
"type": "git",
"url": "git+https://github.com/mattpocock/tt-package-demo.git"
},
"files": ["dist"],
"type": "module"
}
name是人们将用来安装你的包的名称。它在npm上必须是唯一的。你可以免费创建组织作用域（例如@total-typescript/demo），这可以帮助它变得独一无二。version是你的包的版本。它应该遵循语义化版本控制：0.0.1格式。每次发布新版本时，你都应该增加这个数字。description和keywords是你的包的简短描述。它们在npm注册表的搜索中列出。homepage是你的包主页的URL。GitHub仓库是一个很好的默认选项，或者如果你有一个文档站点的话。bugs是人们可以报告你的包问题的地方的URL。author是你！你可以选择性地添加你的电子邮件和网站。如果你有多个贡献者，你可以使用相同的格式将它们指定为contributors数组。repository是你的包的仓库的URL。这在npm注册表上创建了一个指向你的GitHub仓库的链接。files是当人们安装你的包时应包括的文件数组。在这种情况下，我们包括了dist文件夹。README.md，package.json和LICENSE默认被包括在内。type设置为module表示你的包使用ECMAScript模块，而不是CommonJS模块。
2.2：添加license字段
在package.json中添加一个license字段。在这里选择一个许可证。我选择了MIT。
{
"license": "MIT"
}
2.3：添加一个LICENSE文件
创建一个名为LICENSE（无扩展名）的文件，包含你的许可证文本。
2.4：添加一个README.md文件
创建一个README.md文件，对你的包进行描述。这里有一个例子：
**tt-package-demo**
Total TypeScript的演示包。
当人们在npm注册表上查看你的包时，这将被显示。
3: TypeScript
在本节中，我们将安装TypeScript，设置一个tsconfig.json，创建一个源文件，创建一个索引文件，设置一个build脚本，运行我们的构建，将dist添加到.gitignore，设置一个ci脚本，以及为我们的tsconfig.json配置DOM。
3.1：安装TypeScript
运行以下命令安装TypeScript：
npm install --save-dev typescript
我们添加--save-dev将TypeScript作为开发依赖项安装。这意味着当人们安装你的包时，它不会被包含在内。
3.2：设置一个tsconfig.json
创建一个包含以下值的tsconfig.json：
{
"compilerOptions": {
/* 基础选项：*/
"esModuleInterop": true,
"skipLibCheck": true,
"target": "es2022",
"allowJs": true,
"resolveJsonModule": true,
"moduleDetection": "force",
"isolatedModules": true,
"verbatimModuleSyntax": true,
/* 严格性 */
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
/* 如果使用TypeScript进行转译：*/
"module": "NodeNext",
"outDir": "dist",
"rootDir": "src",
"sourceMap": true,
/* 并且如果你正在为库构建：*/
"declaration": true,
/* 并且如果你正在为monorepo中的库构建：*/
"declarationMap": true
}
}
这些选项在我的TSConfig备忘单中有详细解释。
3.3：为你的tsconfig.json配置DOM
如果你的代码在DOM中运行（即需要访问document、window或localStorage等），则跳过这一步。
如果你的代码不需要访问DOM API，将以下内容添加到你的tsconfig.json：
{
"compilerOptions": {
// ...其他选项
"lib": ["es2022"]
}
}
这将防止DOM类型声明在你的代码中可用。
如果你不确定，跳过这一步。
3.4：创建一个源文件
创建一个包含以下内容的src/utils.ts文件：
export const add = (a: number, b: number) => a + b;
3.5：创建一个索引文件
创建一个包含以下内容的src/index.ts文件：
export { add } from "./utils.js";
.js扩展名看起来可能有些奇怪。这篇文章解释了更多。
3.6：设置一个build脚本
将以下内容添加到你的package.json的scripts对象中：
{
"scripts": {
"build": "tsc"
}
这将编译你的TypeScript代码为JavaScript。
3.7：运行你的构建
运行以下命令编译你的TypeScript代码：
npm run build
这将在dist文件夹中创建你编译后的JavaScript代码。
3.8：将dist添加到.gitignore
将dist文件夹添加到你的.gitignore文件中：
dist
这将防止你编译后的代码被包含在你的git仓库中。
3.9：设置一个ci脚本
将以下内容添加到你的package.json的ci脚本中：
{
"scripts": {
"ci": "npm run build"
}
}
这为我们在CI上运行所有必需的操作提供了一个快捷方式。
4: Prettier
在本节中，我们将安装Prettier，设置一个.prettierrc，设置一个format脚本，运行format脚本，设置一个check-format脚本，将check-format脚本添加到我们的CI脚本中，并运行CI脚本。
Prettier是一个代码格式化工具，它会自动将你的代码格式化为一致的风格。这使你的代码更容易阅读和维护。
4.1：安装Prettier
运行以下命令安装Prettier：
npm install --save-dev prettier
4.2：设置一个.prettierrc
创建一个包含以下内容的.prettierrc文件：
{
"semi": true,
"singleQuote": true,
"trailingComma": "all",
"printWidth": 80,
"tabWidth": 2
}
你可以向此文件添加更多选项以自定义Prettier的行为。你可以在这里找到完整的选项列表。
4.3：设置一个format脚本
将以下内容添加到你的package.json的format脚本中：
{
"scripts": {
"format": "prettier --write ."
}
}
这将使用Prettier格式化你项目中的所有文件。
4.4：运行format脚本
运行以下命令格式化你项目中的所有文件：
npm run format
你可能会发现一些文件发生了变化。提交它们：
git add .
git commit -m "使用Prettier格式化代码"
4.5：设置一个check-format脚本
将以下内容添加到你的package.json的check-format脚本中：
{
"scripts": {
"check-format": "prettier --check ."
}
}
这将检查你项目中的所有文件是否已正确格式化。
4.6：添加到我们的CI脚本
将check-format脚本添加到你的package.json中的ci脚本：
{
"scripts": {
"ci": "npm run build && npm run check-format"
}
}
这将作为你CI流程的一部分运行check-format脚本。
5: exports, main 和 @arethetypeswrong/cli
在本节中，我们将安装@arethetypeswrong/cli，设置一个check-exports脚本，运行check-exports脚本，设置一个main字段，再次运行check-exports脚本，设置一个ci脚本，并运行ci脚本。
@arethetypeswrong/cli是一个检查你的包导出是否正确的工具。这很重要，因为这些地方容易出错，可能会给使用你的包的人带来问题。
5.1：安装@arethetypeswrong/cli
运行以下命令安装@arethetypeswrong/cli：
npm install --save-dev @arethetypeswrong/cli
5.2：设置一个check-exports脚本
将以下内容添加到你的package.json的check-exports脚本中：
{
"scripts": {
"check-exports": "attw --pack ."
}
}
这将检查你的包的所有导出是否正确。
5.3：运行check-exports脚本
运行以下命令检查你的包的所有导出是否正确：
npm run check-exports
你应该会注意到各种错误：
| "tt-package-demo" | |
|---|---|
| node10 | 💀 Resolution failed |
| node16 (from CJS) | 💀 Resolution failed |
| node16 (from ESM) | 💀 Resolution failed |
| bundler | 💀 Resolution failed |
这表明没有任何版本的Node或任何打包器可以使用我们的包。
让我们来解决这个问题。
5.4：设置main
在package.json中添加一个main字段，包含以下内容：
{
"main": "dist/index.js"
}
这告诉Node在哪里找到你包的入口点。
5.5：再次尝试check-exports
运行以下命令检查你的包的所有导出是否正确：
npm run check-exports
你应该会注意到只有一个警告：
| "tt-package-demo" | |
|---|---|
| node10 | 🟢 |
| node16 (from CJS) | ⚠️ ESM （仅限动态导入） |
| node16 (from ESM) | 🟢 （ESM） |
| bundler | 🟢 |
这告诉我们，我们的包与运行ESM的系统兼容。使用CJS的人（通常是在旧系统中）将需要使用动态导入来导入它。
5.6 修复CJS警告
如果你不想支持CJS（我建议这样做），将check-exports脚本更改为：
{
"scripts": {
"check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm"
}
}
现在，运行check-exports将显示一切正常：
| "tt-package-demo" | |
|---|---|
| node10 | 🟢 |
| node16 (from CJS) | 🟢 （ESM） |
| node16 (from ESM) | 🟢 （ESM） |
| bundler | 🟢 |
如果你想同时发布CJS和ESM，跳过这一步。
5.7：添加到我们的CI脚本
将check-exports脚本添加到你的package.json中的ci脚本：
{
"scripts": {
"ci": "npm run build && npm run check-format && npm run check-exports"
}
}
6: 使用tsup双重发布
如果你想同时发布CJS和ESM代码，你可以使用tsup。这是基于esbuild构建的工具，它可以将你的TypeScript代码编译成两种格式。
我个人的建议是跳过这一步，只发布ES模块。这将显著简化你的设置，并避免双重发布带来的许多陷阱，比如双重包风险。
但如果你想这样做，那就继续。
6.1：安装tsup
运行以下命令安装tsup：
npm install --save-dev tsup
6.2：创建一个tsup.config.ts文件
创建一个包含以下内容的tsup.config.ts文件：
import { defineConfig } from "tsup";
export default defineConfig({
entryPoints: ["src/index.ts"],
format: ["cjs", "esm"],
dts: true,
outDir: "dist",
clean: true,
});
entryPoints是你包的入口点数组。在这种情况下，我们使用src/index.ts。format是输出格式的数组。我们使用cjs（CommonJS）和esm（ECMAScript模块）。dts是一个布尔值，告诉tsup生成声明文件。outDir是编译代码的输出目录。clean告诉tsup在构建之前清理输出目录。
#### 6.3：更改build脚本
将package.json中的build脚本更改为以下内容：
{
"scripts": {
"build": "tsup"
}
}
我们现在将运行tsup来编译我们的代码，而不是tsc。
6.4：添加一个exports字段
在package.json中添加一个exports字段，包含以下内容：
{
"exports": {
"./package.json": "./package.json",
".": {
"import": "./dist/index.js",
"default": "./dist/index.cjs"
}
}
}
exports字段告诉使用你包的程序如何找到你包的CJS和ESM版本。在这种情况下，我们将使用import的人指向dist/index.js，将使用require的人指向dist/index.cjs。
还建议将./package.json添加到exports字段。这是因为某些工具需要轻松访问你的package.json文件。
6.5：再次尝试check-exports
运行以下命令检查你的包的所有导出是否正确：
npm run check-exports
现在，一切都是绿色的：
| "tt-package-demo" | |
|---|---|
| node10 | 🟢 |
| node16 (from CJS) | 🟢 （CJS） |
| node16 (from ESM) | 🟢 （ESM） |
| bundler | 🟢 |
6.6：将TypeScript变成一个linter
我们不再运行tsc来编译我们的代码。而且tsup实际上并不检查我们的代码是否有错误 - 它只是将其转换为JavaScript。
这意味着如果我们的代码中有TypeScript错误，我们的ci脚本也不会出错。哎呀。
让我们来解决这个问题。
6.6.1：在tsconfig.json中添加noEmit
在tsconfig.json中添加一个noEmit字段：
{
"compilerOptions": {
// ...其他选项
"noEmit": true
}
}
6.6.2：从tsconfig.json中移除未使用的字段
从你的tsconfig.json中移除以下字段：
outDirrootDirsourceMapdeclarationdeclarationMap
它们在我们的新'linting'设置中不再需要。
6.6.3：将module更改为Preserve
可选地，你现在可以将tsconfig.json中的module更改为Preserve：
{
"compilerOptions": {
// ...其他选项
"module": "Preserve"
}
}
这意味着你将不再需要使用.js扩展名来导入你的文件。这意味着index.ts可以这样写：
export * from "./utils";
6.6.4：添加一个lint脚本
将以下内容添加到你的package.json的lint脚本中：
{
"scripts": {
"lint": "tsc"
}
}
这将运行TypeScript作为一个linter。
6.6.5：将lint添加到你的ci脚本
将lint脚本添加到你的package.json中的ci脚本：
{
"scripts": {
"ci": "npm run build && npm run check-format && npm run check-exports && npm run lint"
}
}
现在，我们的CI流程中将包括TypeScript错误。
7: 使用Vitest进行测试
在本节中，我们将安装vitest，创建一个测试，设置一个test脚本，运行test脚本，设置一个dev脚本，并将test脚本添加到我们的CI脚本。
vitest是一个用于ESM和TypeScript的现代测试运行器。它就像Jest，但更好。
7.1：安装vitest
运行以下命令安装vitest：
npm install --save-dev vitest
7.2：创建一个测试
创建一个包含以下内容的src/utils.test.ts文件：
import { add } from "./utils.js";
import { test, expect } from "vitest";
test("add", () => {
expect(add(1, 2)).toBe(3);
});
这是一个简单的测试，检查add函数是否返回正确的值。
7.3：设置test脚本
将以下内容添加到你的package.json的test脚本中：
{
"scripts": {
"test": "vitest run"
}
}
vitest run会一次性运行你项目中的所有测试，不处于监听模式。
7.4：运行test脚本
运行以下命令运行你的测试：
npm run test
你应该看到以下输出：
✓ src/utils.test.ts (1)
✓ hello
测试文件 1 个通过（1）
测试 1 个通过（1）
这表明你的测试已成功通过。
7.5：设置dev脚本
一种常见的工作流程是在开发时以监听模式运行测试。将以下内容添加到你的package.json的dev脚本中：
{
"scripts": {
"dev": "vitest"
}
}
这将以监听模式运行你的测试。
7.6：添加到我们的CI脚本
将test脚本添加到你的package.json中的ci脚本：
{
"scripts": {
"ci": "npm run build && npm run check-format && npm run check-exports && npm run lint && npm run test"
}
}
8. 使用GitHub Actions设置我们的CI
在本节中，我们将创建一个GitHub Actions工作流程，每次提交和拉取请求时都运行我们的CI流程。
这是确保我们的包始终处于工作状态的关键步骤。
8.1：创建我们的工作流程
创建一个包含以下内容的.github/workflows/ci.yml文件：
name: CI
on:
pull_request:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
- name: Install dependencies
run: npm install
- name: Run CI
run: npm run ci
这个文件是GitHub用来运行你的CI流程的指令。
name是工作流程的名称。on指定了工作流程应该何时运行。在这种情况下，它在拉取请求和推送到main分支时运行。concurrency防止多个工作流程实例同时运行，使用cancel-in-progress取消任何正在进行的运行。jobs是运行的一组作业。在这种情况下，我们有一个名为ci的作业。actions/checkout@v4从仓库中检出代码。actions/setup-node@v4设置Node.js和npm。npm install安装项目的依赖项。npm run ci运行项目的CI脚本。
如果我们的CI流程的任何部分失败，工作流程将失败，GitHub会通过在提交旁边显示一个红色的叉来通知我们。
8.2：测试我们的工作流程
将更改推送到GitHub，并检查仓库的Actions选项卡。你应该看到你的工作流程正在运行。
这将在每次提交和每次向仓库提出的PR时给出警告。
9. 使用Changesets发布
在本节中，我们将安装@changesets/cli，初始化Changesets，使Changeset发布公开，将commit设置为true，设置一个local-release脚本，添加一个Changeset，提交你的更改，运行local-release脚本，最后在npm上看到你的包。
Changesets是一个帮助你对包进行版本控制和发布的工具。这是一个令人难以置信的工具，我向任何在npm上发布包的人推荐。
9.1：安装@changesets/cli
运行以下命令初始化Changesets：
npm install --save-dev @changesets/cli
9.2：初始化Changesets
运行以下命令初始化Changesets：
npx changeset init
这将在你的项目中创建一个.changeset文件夹，包含一个config.json文件。这也是你的Changesets所在的地方。
9.3：使Changeset发布公开
在.changeset/config.json中，将access字段更改为public：
// .changeset/config.json
{
"access": "public"
}
如果不更改这个字段，changesets不会将你的包发布到npm。
9.4：将commit设置为true：
在.changeset/config.json中，将commit字段更改为true：
// .changeset/config.json
{
"commit": true
}
这将在版本控制后将Changeset提交到你的仓库。
9.5：设置一个local-release脚本
将以下内容添加到你的package.json的local-release脚本中：
{
"scripts": {
"local-release": "changeset version && changeset publish"
}
}
这个脚本将运行你的CI流程，然后发布你的包到npm。当你想从本地机器发布新版本的包时，将运行此命令。
9.6 在prepublishOnly中运行CI
将以下内容添加到你的package.json的prepublishOnly脚本中：
{
"scripts": {
"prepublishOnly": "npm run ci"
}
}
这将在发布你的包到npm之前自动运行你的CI流程。
这有助于将local-release脚本分开，以防用户意外运行npm publish而没有运行local-release。感谢Jordan Harband的建议！
9.7：添加一个Changeset
运行以下命令添加一个Changeset：
npx changeset
这将打开一个交互式提示，你可以在其中添加一个Changeset。Changesets是将更改分组并给它们一个版本号的一种方式。
将此发布标记为patch发布，并给出一个像“初始发布”这样的描述。
这将在.changeset文件夹中创建一个新文件，包含Changeset。
9.8：提交你的更改
将你的更改提交到你的仓库：
git add .
git commit -m "准备初始发布"
9.9：运行local-release脚本
运行以下命令发布你的包：
npm run local-release
这将运行你的CI流程，对你的包进行版本控制，并将其发布到npm。
它将在你的仓库中创建一个CHANGELOG.md文件，详细说明此版本中的更改。每次发布时都会更新。
9.10：在npm上看到你的包
访问：
http://npmjs.com/package/<你的包名称>
你应该在那里看到你的包！你做到了！你已经发布到npm了！
总结
你现在拥有一个完全设置好的包。你已经设置了：
- 一个带有最新设置的TypeScript项目
- Prettier，它可以格式化你的代码并检查它是否正确格式化
@arethetypeswrong/cli，它检查你的包导出是否正确tsup，它将你的TypeScript代码编译成JavaScriptvitest，它运行你的测试- GitHub Actions，它运行你的CI流程
- Changesets，它对你的包进行版本控制和发布
对于进一步阅读，我建议设置Changesets GitHub action和PR bot，以自动建议贡献者在他们的PR中添加Changesets。它们都是极好的工具。
146