AdonisJS 中文文档

主题

TypeScript 构建过程 ​

用 TypeScript 编写的应用程序必须编译成 JavaScript 才能在生产环境中运行。

编译 TypeScript 源文件可以使用许多不同的构建工具来执行。但是，在 AdonisJS 中，我们坚持使用最直接的方法，使用以下经过时间考验的工具。

TIP

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

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

  • TS Node Maintained 是 TypeScript 的即时编译器。它允许你执行 TypeScript 文件而无需将它们编译为 JavaScript，是开发的绝佳工具。

  • SWC 是用 Rust 编写的 TypeScript 编译器。我们在开发期间与 TS Node 一起使用它，使 JIT 过程极其快速。

工具用途类型检查
TSC创建生产构建是
TS Node开发否
SWC开发否

无需编译执行 TypeScript 文件 ​

你可以使用 ts-node-maintained/register/esm 钩子执行 TypeScript 文件而无需编译它们。例如，你可以通过运行以下命令启动 HTTP 服务器。

sh
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 文件重复此过程。例如：

sh
// title: 运行测试
node --import=ts-node-maintained/register/esm bin/test.ts
sh
// title: 运行 ace 命令
node --import=ts-node-maintained/register/esm bin/console.ts
sh
// title: 运行其他 TypeScript 文件
node --import=ts-node-maintained/register/esm path/to/file.ts

关于文件扩展名的说明 ​

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

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

TIP

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

由于某些运行时允许你"就地"运行 TypeScript 代码并需要 .ts 扩展名，你可能更愿意已经使用 .ts 扩展名以实现未来的兼容性。

运行开发服务器 ​

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

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

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

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

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

sh
node ace serve --watch --no-assets

向 Node.js 命令行传递选项 ​

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

sh
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 文件夹。

WARNING

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

就是这样！

sh
node ace build

创建构建后，你可以 cd 进入 build 文件夹，安装生产依赖项，然后运行你的应用程序。

sh
cd build

# 安装生产依赖项
npm ci --omit=dev

# 运行服务器
node bin/server.js

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

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

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

sh
node ace build --no-assets

什么是独立构建？ ​

独立构建是指你的应用程序的 JavaScript 输出，你可以在没有原始 TypeScript 源码的情况下运行它。

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

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