TypeScript

TypeScript 是 Cloudflare Workers 上的一流语言。Workers 提供的所有 API 都具有完整类型，类型定义直接从开源 Workers 运行时 workerd ↗ 生成。

我们建议你通过运行 wrangler types 为 Worker 生成类型。Cloudflare 还将类型定义发布到 GitHub ↗ 和 npm ↗（npm install -D @cloudflare/workers-types）。

生成与 Worker 配置匹配的类型

Cloudflare 持续改进开源 Workers 运行时 workerd ↗。 workerd 中的变更可能引入 JavaScript API 变更，从而改变相应的 TypeScript 类型。

这意味着 Worker 的正确类型取决于：

1. Worker 的兼容性日期。
2. Worker 的兼容性标志。
3. Worker 的绑定（binding），在 Wrangler 配置文件中定义。
4. 在 Wrangler 配置文件 rules 下指定的任何模块规则。

例如，只有当你在 Wrangler 配置文件中设置了 compatibility_flags = ["nodejs_als"] 时，运行时才会允许你使用 AsyncLocalStorage ↗ 类。这应反映在类型定义中。

为确保类型定义始终与 Worker 配置匹配，你可以通过运行以下命令动态生成类型：

npx wrangler types

yarn wrangler types

pnpm wrangler types

有关更多详情，请参阅 wrangler types 命令文档。

这将生成一个 d.ts 文件，并（默认）保存到 worker-configuration.d.ts。其中将包含基于 Worker 绑定的 Env 类型，以及基于 Worker 兼容性日期和标志的运行时类型。

然后，你应将该文件添加到 tsconfig.json 的 compilerOptions.types 数组中。如果你启用了 nodejs_compat 兼容性标志，还应安装 @types/node。

如果需要，你可以将类型文件提交到 git。

从 @cloudflare/workers-types 迁移到 wrangler types

我们建议你使用 wrangler types 生成运行时类型，而不是使用 @cloudflare/workers-types 包，因为它会根据 Worker 的兼容性日期 ↗和 compatibility_flags 生成类型，确保类型与 Worker 可用的确切运行时 API 匹配。

npm uninstall @cloudflare/workers-types

yarn remove @cloudflare/workers-types

pnpm remove @cloudflare/workers-types

bun remove @cloudflare/workers-types

npx wrangler types

yarn wrangler types

pnpm wrangler types

这将生成一个 .d.ts 文件，默认保存到 worker-configuration.d.ts。这还将生成 Env 类型。如果出于某种原因你不想包含这些类型，可以设置 --include-env=false。

现在，你可以从 Worker 代码中移除所有来自 @cloudflare/workers-types 的导入。

{
	"compilerOptions": {
		"types": ["./worker-configuration.d.ts"]
	}
}

请注意，如果你为运行时类型文件指定了自定义路径，应在 compilerOptions.types 数组中使用该路径，而不是默认路径。

如果你使用 nodejs_compat 兼容性标志，还应安装 @types/node。

npm i @types/node

yarn add @types/node

pnpm add @types/node

bun add @types/node

然后将其添加到你的 tsconfig.json。

{
	"compilerOptions": {
		"types": ["./worker-configuration.d.ts", "node"]
	}
}

无论你的具体框架或构建工具是什么，你都应在依赖 TypeScript 的任何任务之前运行 wrangler types 命令。

大多数项目都有现有的构建和开发脚本，以及一些类型检查。在下面的示例中，我们在项目的类型检查脚本之前添加了 wrangler types：

{
	"scripts": {
		"dev": "existing-dev-command",
		"build": "existing-build-command",
		"generate-types": "wrangler types",
		"type-check": "generate-types && tsc"
	}
}

我们建议你为 CI 使用提交生成的类型文件。你可以在其他 CI 命令之前运行 wrangler types，因为它不应超过几秒钟。例如：

- run: npm run generate-types
- run: npm run build
- run: npm test

- run: yarn generate-types
- run: yarn build
- run: yarn test

- run: pnpm run generate-types
- run: pnpm run build
- run: pnpm test

或者，如果你提交了生成的类型文件并希望在 CI 中验证它保持最新，可以使用 --check 标志：

- run: npx wrangler types --check
- run: npm run build
- run: npm test

- run: yarn wrangler types --check
- run: yarn build
- run: yarn test

- run: pnpm wrangler types --check
- run: pnpm run build
- run: pnpm test

如果提交的类型文件已过期，这将导致 CI 作业失败，提示开发者重新生成并提交更新的类型。

• TypeScript 模板 ↗
• @cloudflare/workers-types ↗
• 运行时 API
• TypeScript 示例