开发环境配置

本指南介绍 AdonisJS 应用推荐的开发环境。你将了解如何：

• 使用必需的编译器选项配置 TypeScript
• 配置 ESLint 与 Prettier 以保障代码质量
• 安装推荐的代码编辑器扩展
• 为本地开发选择数据库

概述

AdonisJS 应用开箱即带有一套完整配置好的开发环境。TypeScript、ESLint 与 Prettier 都已按合理默认值预配置，让你无需手动设置即可立即开始构建。

本指南将解释项目中已经配置了哪些内容，推荐可提升开发体验的可选编辑器扩展，并提供为本地开发选择数据库的指导。理解这些配置有助于你充分发挥框架的能力，并在团队中保持一致性。

代码编辑器与扩展

AdonisJS 兼容任何支持 TypeScript 的现代代码编辑器。框架不依赖自定义的领域特定语言（DSL），因此大多数编辑器都能开箱即用地提供完整的语言支持。唯一的框架特定语法是 Edge 模板引擎，它受益于专门的高亮显示扩展。

AdonisJS Extension

为 AdonisJS API 提供 IntelliSense、文件生成器，以及与命令面板集成的 Ace 命令运行能力。

VSCode

Japa Extension

测试运行器集成，可直接从编辑器运行单个测试或测试套件。

VSCode

Edge Templates Extension

为 Edge 模板文件提供完整语法高亮与基础自动补全。

VSCode Zed Sublime Text

TypeScript 配置

TypeScript 是 AdonisJS 中的一等公民。每个应用默认都使用 TypeScript 创建并运行，所有配置都会自动处理。理解 TypeScript 在开发环境与生产环境中的差异，以及必需的编译器选项，有助于你就部署与工具链做出明智决策。

必需的 TypeScript 配置

AdonisJS 需要特定的 TypeScript 编译器选项才能正常工作。框架重度依赖**实验性装饰器（experimental decorators）**来实现依赖注入、模型定义与 Ace 命令。

以下 tsconfig.json 配置代表了 AdonisJS 应用所需的最低要求。

{
  "compilerOptions": {
    "module": "NodeNext",
    "isolatedModules": true,
    "declaration": false,
    "outDir": "./build",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true
  },
  "include": ["**/*", ".adonisjs/server/**/*"]
}

{
  "compilerOptions": {
    "module": "NodeNext",
    "isolatedModules": true,
    "declaration": false,
    "outDir": "./build",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true
  },
  "references": [
    {
      "path": "./inertia/tsconfig.json"
    }
  ],
  "include": ["**/*", ".adonisjs/server/**/*"]
}

开发模式（JIT 编译）

在开发环境中，AdonisJS 使用 @poppinss/ts-exec 包提供的即时（JIT）编译器。这种方式无需单独的编译步骤即可直接执行 TypeScript 文件，在你保存改动时提供即时反馈。

这与 Node.js 原生的 TypeScript 支持不同，因为 AdonisJS 需要：

• 实验性装饰器支持（用于依赖注入与模型装饰器）
• JSX 编译（如果你用基于 JSX 的模板引擎如 Inertia 替换 Edge）

由于 Node.js 内置的 TypeScript 加载器不支持这些特性， @poppinss/ts-exec 提供了必要的兼容层。

生产模式（提前编译）

对于生产部署，AdonisJS 使用官方 TypeScript 编译器（tsc）将你的 TypeScript 代码编译为 JavaScript。该过程会生成一个 build/ 目录，其中包含针对 Node.js 运行时优化的转译后 .js 文件。

node ace build

编译后的产物包含：

• 装饰器已被转换的转译 JavaScript 文件
• 复制过来的静态资源与模板
• package.json 以及你的包管理器锁文件。你必须 cd 进入 build 目录，安装依赖并启动生产服务器。

另请参阅： 部署到生产环境

ESLint 与 Prettier 配置

AdonisJS 项目包含预配置好的 ESLint 与 Prettier，它们会强制执行 TypeScript 最佳实践，并在团队中保持一致的代码格式。

ESLint

默认的 ESLint 配置继承自 AdonisJS 基础配置，其中包含针对 TypeScript、async/await 模式以及框架约定的规则。你可以按需覆盖或扩展 eslint.config.js 中的这些规则。

import { configApp } from '@adonisjs/eslint-config'
export default configApp()

手动运行 ESLint：

npm run lint

Prettier

Prettier 配置定义在 package.json 中，确保所有文件格式一致。AdonisJS 预设包含针对缩进、引号与行宽的合理默认值。

{
  "prettier": "@adonisjs/prettier-config"
}

手动运行 Prettier：

npm run format

另请参阅： ESLint 配置参考 、 Prettier 配置参考

数据库配置

AdonisJS 应用预配置使用 SQLite——一个轻量的基于文件的数据库。SQLite 无需安装，将数据存储在本地的 tmp/database.sqlite 文件中，让你无需搭建外部数据库服务器即可立即开始构建。

不过，大多数应用在生产环境中会使用 PostgreSQL 或 MySQL。我们建议尽早 切换到你的生产数据库 引擎，以避免可能引发部署问题的 schema 差异与驱动相关行为。

本地数据库工具

你可以使用以下工具在本地运行 PostgreSQL 或 MySQL：

• Dbngin （macOS 和 Windows），通过 GUI 管理 PostgreSQL 和 MySQL
• Docker ，在隔离容器中运行数据库
• Postgres.app ，在 macOS 上运行原生 PostgreSQL