TypeScript 构建流程

TypeScript 构建流程

用 TypeScript 编写的应用必须先编译成 JavaScript，然后才能在生产环境中运行。

编译 TypeScript 源文件可以使用许多不同的构建工具来完成。不过，在 AdonisJS 中，我们坚持最简方案，使用以下经过时间检验的工具。

以下提到的所有工具都已作为开发依赖随官方启动套件预装。

  • TSC 是 TypeScript 官方的编译器。我们使用 TSC 来执行类型检查并创建生产构建。

  • TS Node Maintained 是一个用于 TypeScript 的即时（Just-in-Time）编译器。它允许你在无需将 TypeScript 编译成 JavaScript 的情况下执行 TypeScript 文件，是开发过程中的绝佳工具。

  • SWC 是一个用 Rust 编写的 TypeScript 编译器。我们在开发期间配合 TS Node 使用它，让 JIT 过程极其迅速。

ToolUsed forType checking
TSC创建生产构建Yes
TS Node开发No
SWC开发No

不编译就执行 TypeScript 文件

你可以使用 ts-node-maintained/register/esm 钩子在不编译的情况下执行 TypeScript 文件。例如，你可以通过运行以下命令来启动 HTTP 服务器。

node --import=ts-node-maintained/register/esm bin/server.js

  • --import：import 标志允许你指定一个模块，该模块导出用于模块解析和加载的自定义钩子。更多信息请参阅 Node.js 自定义钩子文档。

  • ts-node-maintained/register/esm：指向 ts-node-maintained/register/esm 脚本的路径，该脚本注册生命周期钩子，以执行将 TypeScript 源代码即时编译为 JavaScript 的过程。

  • bin/server.js：AdonisJS HTTP 服务器入口文件的路径。另请参阅：关于文件扩展名的说明

你也可以对其他 TypeScript 文件重复此过程。例如：

Run tests 
node --import=ts-node-maintained/register/esm bin/test.ts
Run ace commands 
node --import=ts-node-maintained/register/esm bin/console.ts
Run some other TypeScript file 
node --import=ts-node-maintained/register/esm path/to/file.ts

关于文件扩展名的说明

你可能已经注意到我们到处都使用 .js 文件扩展名，即使磁盘上的文件是以 .ts 扩展名保存的。

这是因为在 ES 模块中，TypeScript 强制你在导入和运行脚本时使用 .js 扩展名。你可以在 TypeScript 文档 中了解这一选择背后的理论依据。

如果你使用的是 TypeScript 5.7 或更高版本，你可以使用 .ts 扩展名导入 TypeScript 文件。这是由相对路径的路径重写特性实现的。

由于某些运行时允许你"原地"运行 TypeScript 代码并要求使用 .ts 扩展名，为了未来的兼容性，你可能更倾向于已经使用 .ts 扩展名。

运行开发服务器

我们建议不要直接运行 bin/server.js 文件，而是使用 serve 命令，原因如下。

  • 该命令包含一个文件监视器，会在文件变更时重启开发服务器。
  • serve 命令会检测你的应用正在使用的前端资源打包器，并启动它的开发服务器。例如，如果你的项目根目录中有一个 vite.config.js 文件，serve 命令就会启动 vite 开发服务器。
node ace serve --watch

你可以使用 --assets-args 命令行标志向 Vite 开发服务器传递参数。

node ace serve --watch --assets-args="--debug --base=/public"

你可以使用 --no-assets 标志来禁用 Vite 开发服务器。

node ace serve --watch --no-assets

向 Node.js 命令行传递选项

serve 命令会将开发服务器（bin/server.ts 文件）作为一个子进程启动。如果你想向该子进程传递 node 参数，可以在命令名之前定义它们。

node ace --no-warnings --inspect serve --watch

创建生产构建

你的 AdonisJS 应用的生产构建是使用 node ace build 命令创建的。build 命令执行以下操作，以在 ./build 目录中创建一个独立的 JavaScript 应用。

  • 删除已存在的 ./build 文件夹（如果有的话）。
  • 从头重写 ace.js 文件，以移除 ts-node/esm 加载器。
  • 使用 Vite 编译前端资源（如果已配置）。
  • 使用 tsc 将 TypeScript 源代码编译为 JavaScript。
  • 将注册在 metaFiles 数组下的非 TypeScript 文件复制到 ./build 文件夹。
  • 将 package.json 和 package-lock.json/yarn.lock 文件复制到 ./build 文件夹。

对 ace.js 文件的任何修改都会在构建过程中丢失，因为该文件是从头重写的。如果你想要在 Ace 启动之前运行任何额外的代码，应该改为在 bin/console.ts 文件中完成。

就是这样！

node ace build

构建完成后，你可以 cd 进入 build 文件夹，安装生产依赖，并运行你的应用。

cd build



# Install production dependencies

npm ci --omit=dev



# Run server

node bin/server.js

你可以使用 --assets-args 命令行标志向 Vite 构建命令传递参数。

node ace build --assets-args="--debug --base=/public"

你可以使用 --no-assets 标志来避免编译前端资源。

node ace build --no-assets

什么是独立构建？

独立构建（standalone build）指的是你应用的 JavaScript 输出，你可以无需原始的 TypeScript 源代码就运行它。

创建独立构建有助于减小部署到生产服务器上的代码体积，因为你无需同时复制源文件和 JavaScript 输出。

创建生产构建后，你可以将 ./build 复制到你的生产服务器，安装依赖，定义环境变量，并运行应用。

© 2026 AdonisJS Edit this page

On this page