安装

在创建新应用之前，你应当确保计算机上已安装 Node.js 和 npm。AdonisJS 需要 Node.js 20 或更高版本。

你可以使用官方安装包或 Volta 安装 Node.js。Volta 是一个跨平台的包管理器，可在你的计算机上安装并运行多个 Node.js 版本。

node -v
# v22.0.0

创建新应用

你可以使用 npm init 创建新项目。这些命令会下载 create-adonisjs 初始化器包并开始安装过程。

你可以使用以下 CLI 标志之一自定义初始项目输出。

• --kit：为项目选择启动套件。你可以在 web、api、slim 或 inertia 之间选择。

• --db：指定你偏好的数据库方言。你可以在 sqlite、postgres、mysql 或 mssql 之间选择。

• --git-init：初始化 git 仓库。默认为 false。

• --auth-guard：指定你偏好的身份认证守卫。你可以在 session、access_tokens 或 basic_auth 之间选择。

npm init adonisjs@latest hello-world

使用 npm init 命令传递 CLI 标志时，务必连续使用两次双横线。否则，npm init 不会将标志传递给 create-adonisjs 初始化器包。例如：

# 创建一个项目，并交互式询问所有选项
npm init adonisjs@latest hello-world

# 创建一个使用 MySQL 的项目
npm init adonisjs@latest hello-world -- --db=mysql

# 创建一个使用 PostgreSQL 和 API 启动套件的项目
npm init adonisjs@latest hello-world -- --db=postgres --kit=api

# 创建一个使用 API 启动套件和 access tokens 守卫的项目
npm init adonisjs@latest hello-world -- --kit=api --auth-guard=access_tokens

启动套件

启动套件是创建 AdonisJS 应用的起点。它们带有约定式的目录结构、预配置的 AdonisJS 软件包，以及开发过程中所需的工具链。

Web 启动套件

Web 启动套件专为创建传统的服务端渲染 Web 应用而设计。不要让"传统"这个词让你却步。如果你要创建一个前端交互有限制的 Web 应用，我们推荐此启动套件。

使用 Edge.js 在服务器端渲染 HTML 的简洁性将提升你的生产力，因为你无需为了渲染一些 HTML 而去处理复杂的构建系统。

之后，你可以使用 Hotwire、HTMX 或 Unpoly 让你的应用像 SPA 一样导航，并使用 Alpine.js 创建下拉菜单、模态框等交互式小组件。

npm init adonisjs@latest -- -K=web

# 切换数据库方言
npm init adonisjs@latest -- -K=web --db=mysql

Web 启动套件包含以下软件包。

API 启动套件

API 启动套件专为创建 JSON API 服务而设计。它是 web 启动套件的精简版本。如果你打算使用 React 或 Vue 构建前端应用，可以使用 API 启动套件创建 AdonisJS 后端。

npm init adonisjs@latest -- -K=api

# 切换数据库方言
npm init adonisjs@latest -- -K=api --db=mysql

在此启动套件中：

• 我们移除了对提供静态文件的支持。
• 不配置视图层和 vite。
• 关闭 XSS 和 CSRF 保护，并启用 CORS 保护。
• 使用 ContentNegotiation 中间件以 JSON 形式发送 HTTP 响应。

API 启动套件默认配置为基于 session 的身份认证。不过，如果你希望使用基于 token 的身份认证，可以使用 --auth-guard 标志。

另见：我应该使用哪种身份认证守卫？

npm init adonisjs@latest -- -K=api --auth-guard=access_tokens

Slim 启动套件

对于极简主义者，我们创建了 slim 启动套件。它只包含框架核心和默认的目录结构。当你不想要 AdonisJS 的任何额外功能时，可以使用它。

npm init adonisjs@latest -- -K=slim

# 切换数据库方言
npm init adonisjs@latest -- -K=slim --db=mysql

Inertia 启动套件

Inertia 是一种构建服务端驱动的单页应用的方式。你可以使用自己喜欢的前端框架（React、Vue、Solid、Svelte）来构建应用的前端。

你可以使用 --adapter 标志选择要使用的前端框架。可用选项为 react、vue、solid 和 svelte。

你还可以使用 --ssr 和 --no-ssr 标志来开启或关闭服务端渲染。

npm init adonisjs@latest -- -K=inertia

# 使用 React 并开启服务端渲染
npm init adonisjs@latest -- -K=inertia --adapter=react --ssr

# 使用 Vue 并关闭服务端渲染
npm init adonisjs@latest -- -K=inertia --adapter=vue --no-ssr

自带启动套件

启动套件是托管在 Git 仓库提供商（如 GitHub、Bitbucket 或 GitLab）上的预构建项目。你也可以创建自己的启动套件并按如下方式下载。

npm init adonisjs@latest -- -K="github_user/repo"

# 从 GitLab 下载
npm init adonisjs@latest -- -K="gitlab:user/repo"

# 从 Bitbucket 下载
npm init adonisjs@latest -- -K="bitbucket:user/repo"

你可以使用 git 模式，通过 Git+SSH 认证下载私有仓库。

npm init adonisjs@latest -- -K="user/repo" --mode=git

最后，你可以指定 tag、分支或 commit。

# 分支
npm init adonisjs@latest -- -K="user/repo#develop"

# Tag
npm init adonisjs@latest -- -K="user/repo#v2.1.0"

启动开发服务器

创建 AdonisJS 应用后，你可以运行 node ace serve 命令启动开发服务器。

Ace 是捆绑在框架核心中的命令行框架。--hmr 标志会监控文件系统，并对代码库的某些部分执行热模块替换（HMR）。

node ace serve --hmr

开发服务器启动后，你可以访问 http://localhost:3333 在浏览器中查看你的应用。

构建生产版本

由于 AdonisJS 应用是用 TypeScript 编写的，在投入生产之前必须编译为 JavaScript。

你可以使用 node ace build 命令生成 JavaScript 输出。JavaScript 输出会被写入 build 目录。

当配置了 Vite 时，此命令还会使用 Vite 编译前端资源，并将输出写入 build/public 文件夹。

另见：TypeScript 构建流程。

node ace build

配置开发环境

AdonisJS 负责构建终端用户应用，但你可能需要额外的工具来享受开发过程并保持编码风格一致。

我们强烈推荐使用 ESLint 检查代码，并使用 Prettier 重新格式化代码以保持一致。

官方启动套件已预配置了 ESLint 和 Prettier，并使用 AdonisJS 核心团队的约定式预设。你可以在文档的工具配置章节了解更多。

最后，我们建议为你的代码编辑器安装 ESLint 和 Prettier 插件，以便在应用开发过程中获得更紧密的反馈循环。此外，你可以使用以下命令从命令行 lint 和 format 你的代码。

# 运行 ESLint
npm run lint

# 运行 ESLint 并自动修复问题
npm run lint -- --fix

# 运行 prettier
npm run format

VSCode 扩展

你可以在任何支持 TypeScript 的代码编辑器上开发 AdonisJS 应用。不过，我们为 VSCode 开发了多个扩展，以进一步提升开发体验。

• AdonisJS - 直接从代码编辑器查看应用路由、运行 ace 命令、执行数据库迁移并阅读文档。

• Edge - 借助语法高亮、自动补全和代码片段支持，让你的开发工作流如虎添翼。

• Japa - 使用键盘快捷键或从活动栏直接运行测试，无需离开代码编辑器。