安装

本指南讲解如何从零搭建一个新的 AdonisJS 应用，涵盖前置条件、项目创建与启动开发服务器。你无需有 AdonisJS 的使用经验，但具备 Node.js 基础知识会很有帮助。

前置条件

在开始之前，请确保已安装以下工具。

• Node.js ≥ 24.x
• npm ≥ 11.x

你可以使用以下命令核实已安装的版本。

node -v
npm -v

在继续之前，请确认你的 Node.js 与 npm 版本满足这些要求。你可以从 Node.js 官网 下载最新版本，或使用 Volta/nvm 这类版本管理器。

创建一个新的应用

AdonisJS 提供了 create-adonisjs 初始化包来为新建应用生成脚手架。该包会根据你在安装过程中的选择，创建一个包含全部必要文件、依赖与配置的新项目目录。

将 [project-name] 替换为你期望的项目名称。初始化程序会创建一个以该名称命名的目录，并在其中搭建你的 AdonisJS 应用。

npm create adonisjs@latest [project-name]

该命令会启动一个交互式安装流程，并询问你要选择哪个入门套件；你也可以预先通过 --kit CLI 选项指定入门套件。

npm create adonisjs@latest [project-name] -- --kit=hypermedia

npm create adonisjs@latest [project-name] -- --kit=react

npm create adonisjs@latest [project-name] -- --kit=vue

npm create adonisjs@latest [project-name] -- --kit=api

官方入门套件

AdonisJS 提供四套官方入门套件。每套套件会根据你构建用户界面与管理交互的方式，搭建不同类型的应用。

• Hypermedia 入门套件 。使用 Edge 作为服务端模板引擎，并集成了 Alpine.js，为前端添加轻量、响应式的交互行为。非常适合主要以服务端渲染 HTML、仅需极少前端逻辑的应用。

• React 入门套件 。将 Inertia.js 与 React 结合，构建由 AdonisJS 后端驱动的全栈 React 应用。根据你的配置，它既可以作为服务端渲染应用，也可以作为单页应用（SPA）运行。

• Vue 入门套件 。与 React 方案类似，但以前端框架 Vue 替代。它同样使用 Inertia.js，并提供相同的全栈能力，包括后端驱动的路由、共享状态与 SPA 支持。

• API 入门套件 。一个 monorepo 结构，包含两大应用：一个 AdonisJS 后端，以及一个空的前端项目，你可以在其中配置任意前端框架（TanStack Start、Nuxt、Next.js 等）。后端与前端之间已配置好端到端的类型安全与共享的转换器类型。

所有入门套件都预置了合理的默认值、精简的开发工作流，以及开箱即用的身份验证功能。如需详细对比与使用指引，请参阅 选择你的技术路线 指南。

社区入门套件

除了官方套件外，AdonisJS 社区也维护着面向特定使用场景的入门套件。

• Slim 入门套件 。一个精简的 AdonisJS v7 初始环境，包含框架核心与 Japa 测试运行器，专为希望从轻量基础起步的团队而设计。

• MCP 入门套件 。一个精简的 AdonisJS v7 初始环境，内置 MCP 支持，适用于你想在应用中暴露 MCP 工具、资源与提示词的场景。

项目默认配置

每个新建的 AdonisJS 应用都包含：

• 约定式的目录结构。
• 已配置 Lucid ORM ，默认数据库为 SQLite。
• 内置登录与注册的身份验证流程。
• 预置 ESLint 与 Prettier 配置。

这些特性能让你快速上手。随着项目发展，你可以按需自定义、扩展或移除它们。

启动开发服务器

创建应用后，进入项目目录并启动开发服务器。

node ace serve --hmr

npm run dev

{ "hello": "world" }

你刚刚安装了什么

你的入门套件包含：

• 预配置的开发环境。TypeScript、ESLint、Prettier 与 Vite 都已按合理默认值设置好。

• 数据库配置。Lucid ORM 已配置为 SQLite，随时可以开始构建模型并运行迁移。

• 有序的项目结构。路由定义在 start/routes.ts，模型位于 app/models/，控制器位于 app/controllers/，中间件位于 app/middleware/。这一约定能让你的代码库在成长过程中保持有序。

• 可用的身份验证。所有入门套件都包含功能完整的身份验证系统，自带注册与登录流程。

开发服务器模式

• 热模块替换（--hmr）。这是大多数开发场景下推荐的方式。HMR 能在不要求整页刷新的情况下更新浏览器中的应用，在即时反映代码改动的同时保留应用状态。这提供了最快的开发反馈循环，尤其是在处理前端组件或样式时。

• 文件监听（--watch）。该模式会在你修改代码时自动重启整个服务器进程。虽然这种方式因需要完整重启而比 HMR 略慢，但它能确保每次改动都获得一个干净的应用状态，在处理服务端逻辑或 HMR 更新无法满足需求时很有用。

探索其他命令

ace 命令行工具包含许多用于开发与生产工作流的命令。

要查看所有可用命令，运行以下指令：

node ace

下一步

• AdonisJS 新手？ 跟随 Tutorial （教程）构建一个完整应用，了解各个部分如何协同工作。
• 想先理解代码库？ 阅读 目录结构 了解项目是如何组织的。