AdonisRC 文件

本指南涵盖 adonisrc.ts 配置文件。你将学习如何：

注册服务提供者并预加载文件
为脚手架命令配置目录路径
为常用 Ace 命令定义命令别名
设置汇编器（assembler）钩子以进行构建时代码生成
指定要包含在生产构建中的 meta 文件
配置测试套件与运行器选项

概述

adonisrc.ts 文件是你的 AdonisJS workspace 的中央配置。它控制框架如何启动、脚手架命令将生成的文件放在何处、要加载哪些提供者，以及构建过程的行为方式。

这个文件会被主应用之外的多个工具处理，包括 Ace CLI、汇编器（负责开发服务器与生产构建）以及各类代码生成器。正因为这种广泛的使用方式，该文件必须保持与环境无关，且不含有应用特定的逻辑。

该文件包含运行你的应用所需的最小配置。你可以通过运行 node ace inspect:rcfile 命令查看包含所有默认值的完整展开后的配置。

node ace inspect:rcfile

你可以使用 app 服务以编程方式访问解析后的 RCFile 内容。

app/services/some_service.ts

import app from '@adonisjs/core/services/app'

console.log(app.rcFile)

directories

directories 对象将逻辑目录名映射到其文件系统路径。脚手架命令使用这些映射来决定将生成的文件放在何处。

如果你重命名了项目结构中的目录，请在此处更新对应的路径，以便像 node ace make:controller 这样的命令能继续正确工作。

adonisrc.ts

{
  directories: {
    config: 'config',
    commands: 'commands',
    contracts: 'contracts',
    public: 'public',
    providers: 'providers',
    languageFiles: 'resources/lang',
    migrations: 'database/migrations',
    seeders: 'database/seeders',
    factories: 'database/factories',
    views: 'resources/views',
    start: 'start',
    tmp: 'tmp',
    tests: 'tests',
    httpControllers: 'app/controllers',
    models: 'app/models',
    services: 'app/services',
    exceptions: 'app/exceptions',
    mailers: 'app/mailers',
    mails: 'app/mails',
    middleware: 'app/middleware',
    policies: 'app/policies',
    validators: 'app/validators',
    events: 'app/events',
    listeners: 'app/listeners',
    transformers: 'app/transformers',
    stubs: 'stubs',
    generatedClient: '.adonisjs/client',
    generatedServer: '.adonisjs/server',
  }
}

preloads

preloads 数组指定在应用启动时导入的文件。这些文件会在服务提供者注册并启动之后立即导入，非常适合那些需要访问容器、但又应在应用开始处理请求之前运行的设置代码。

你可以注册一个在所有环境中都运行的预加载文件，或者将其限制在特定环境中。

环境	描述
`web`	HTTP 服务器进程
`console`	Ace 命令（REPL 除外）
`repl`	交互式 REPL 会话
`test`	测试运行器进程

最简单的形式是注册一个在所有环境中运行的文件。

adonisrc.ts

{
  preloads: [
    () => import('#start/view')
  ]
}

要将预加载文件限制在特定环境中，请使用带有 environment 数组的对象形式。

adonisrc.ts

{
  preloads: [
    {
      file: () => import('#start/view'),
      environment: ['web', 'console', 'test']
    },
  ]
}

Note

你可以使用 node ace make:preload 命令创建并注册预加载文件。

providers

providers 数组列出在应用启动时加载的服务提供者。提供者按照它们在数组中的出现顺序加载，当提供者彼此依赖时这一点很重要。

与预加载文件一样，提供者可以注册为在所有环境中加载，也可以使用相同的环境值 web、console、repl 和 test 限制在特定环境中。

adonisrc.ts

{
  providers: [
    () => import('@adonisjs/core/providers/app_provider'),
    () => import('@adonisjs/core/providers/http_provider'),
    () => import('@adonisjs/core/providers/hash_provider'),
    () => import('./providers/app_provider.js'),
  ]
}

要仅在特定环境中加载提供者，请使用对象形式。

adonisrc.ts

{
  providers: [
    () => import('@adonisjs/core/providers/app_provider'),
    () => import('@adonisjs/core/providers/hash_provider'),
    {
      file: () => import('@adonisjs/core/providers/http_provider'),
      environment: ['web']
    },
    {
      file: () => import('./providers/app_provider.js'),
      environment: ['web', 'console', 'test']
    },
  ]
}

另请参阅：服务提供者

commands

commands 数组注册来自已安装包的 Ace 命令。你的应用自身的命令（在 commands 目录中）会被自动发现，无需在此注册。

adonisrc.ts

{
  commands: [
    () => import('@adonisjs/core/commands'),
    () => import('@adonisjs/lucid/commands')
  ]
}

另请参阅：创建 Ace 命令

commandsAliases

commandsAliases 对象为常用命令创建快捷方式。这对于名称较长的命令或你经常运行的命令很有用。

adonisrc.ts

{
  commandsAliases: {
    migrate: 'migration:run'
  }
}

你可以定义多个指向同一命令的别名。

adonisrc.ts

{
  commandsAliases: {
    migrate: 'migration:run',
    up: 'migration:run'
  }
}

另请参阅：创建命令别名

hooks

hooks 对象注册在汇编器生命周期的特定节点运行的回调。汇编器是负责运行开发服务器、创建生产构建、运行测试以及执行代码生成的工具。

钩子可以以内联方式定义，也可以作为惰性导入的模块定义。它们在独立于你的 AdonisJS 应用的进程中运行，无法访问 IoC 容器或框架服务。

adonisrc.ts

import { defineConfig } from '@adonisjs/core/app'
import { indexEntities } from '@adonisjs/core/app'

export default defineConfig({
  hooks: {
    init: [indexEntities()],
    buildStarting: [() => import('@adonisjs/vite/build_hook')],
  },
})

indexEntities() 钩子为控制器、事件和监听器生成 barrel 文件，从而启用惰性加载和类型安全的引用。像 @adonisjs/vite/build_hook 这样的包钩子负责构建时代的资源编译。

另请参阅：汇编器钩子，以获取可用钩子的完整参考，以及如何为代码生成创建自定义钩子。

metaFiles

metaFiles 数组指定在创建生产构建时要复制到 build 文件夹的非 TypeScript 文件。这包括模板、语言文件以及应用运行时所需的其他资源。

每个条目接受一个 glob 模式和一个可选的 reloadServer 标志，该标志会在匹配的文件发生变化时触发开发服务器重启。

属性	描述
`pattern`	用于匹配文件的 glob 模式
`reloadServer`	这些文件发生变化时是否重启开发服务器

adonisrc.ts

{
  metaFiles: [
    {
      pattern: 'public/**',
      reloadServer: false
    },
    {
      pattern: 'resources/views/**/*.edge',
      reloadServer: false
    }
  ]
}

tests

tests 对象配置测试运行器，包括全局超时设置和测试套件定义。

adonisrc.ts

{
  tests: {
    timeout: 2000,
    forceExit: false,
    suites: [
      {
        name: 'functional',
        files: ['tests/functional/**/*.spec.ts'],
        timeout: 30000
      }
    ]
  }
}

属性	描述
`timeout`	所有测试的默认超时时间，单位为毫秒
`forceExit`	测试完成后是否强制退出进程。建议使用优雅退出
`suites[].name`	测试套件的唯一标识符
`suites[].files`	用于发现测试文件的 glob 模式
`suites[].timeout`	覆盖全局默认值的套件特定超时时间

另请参阅：测试简介

命令了解 AdonisJS 框架核心及官方包随附的命令。