AdonisJS 中文文档

主题

安装 ​

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

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

sh
// title: 验证 Node.js 版本
node -v
# v22.0.0

TIP

你更喜欢视觉学习吗？ - 查看我们的朋友 Adocasts 的 Let's Learn AdonisJS 6 免费视频教程系列。

创建新应用程序 ​

你可以使用 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。

:::codegroup

sh
// title: npm
npm init adonisjs@latest hello-world

:::

使用 npm init 命令传递 CLI 标志时，确保使用双破折号两次。否则，npm init 不会将标志传递给 create-adonisjs 初始化包。例如：

sh
# 创建项目并提示所有选项
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 入门套件和访问令牌守卫创建项目
npm init adonisjs@latest hello-world -- --kit=api --auth-guard=access_tokens

入门套件 ​

入门套件作为使用 AdonisJS 创建应用程序的起点。它们带有有主见的文件夹结构、预配置的 AdonisJS 包和开发期间需要的必要工具。

TIP

官方入门套件使用 ES 模块和 TypeScript。这种组合允许你使用现代 JavaScript 构造并利用静态类型安全。

Web 入门套件 ​

Web 入门套件专为创建传统服务器渲染 web 应用而定制。不要让"传统"这个词吓到你。如果你要制作一个前端交互性有限的 web 应用，我们推荐这个入门套件。

使用 Edge.js 在服务器上渲染 HTML 的简单性将提高你的生产力，因为你不必处理复杂的构建系统来渲染一些 HTML。

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

sh
npm init adonisjs@latest -- -K=web

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

web 入门套件附带以下包。

包描述
@adonisjs/core框架的核心，具有创建后端应用程序时可能需要的基本功能。
edge.js用于组合 HTML 页面的 edge 模板引擎。
@vinejs/vineVineJS 是 Node.js 生态系统中最快的验证库之一。
@adonisjs/lucidLucid 是由 AdonisJS 核心团队维护的 SQL ORM。
@adonisjs/auth框架的认证层。它被配置为使用会话。
@adonisjs/shield一组安全原语，保护你的 web 应用免受 CSRF 和 XSS 等攻击。
@adonisjs/static从应用程序的 /public 目录提供静态资源的中间件。
viteVite 用于编译前端资源。

API 入门套件 ​

API 入门套件专为创建 JSON API 服务器而定制。它是 web 入门套件的精简版本。如果你计划使用 React 或 Vue 构建前端应用，可以使用 API 入门套件创建 AdonisJS 后端。

sh
npm init adonisjs@latest -- -K=api

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

在这个入门套件中：

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

API 入门套件配置了基于会话的认证。但是，如果你希望使用基于令牌的认证，可以使用 --auth-guard 标志。

另请参阅：我应该使用哪个认证守卫？

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

Slim 入门套件 ​

对于极简主义者，我们创建了 slim 入门套件。它只附带框架核心和默认文件夹结构。当你不需要 AdonisJS 的任何附加功能时可以使用它。

sh
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 标志来打开或关闭服务器端渲染。

sh
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）上的预构建项目。你也可以创建自己的入门套件并按如下方式下载。

sh
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 认证下载私有仓库。

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

最后，你可以指定标签、分支或提交。

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

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

启动开发服务器 ​

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

Ace 是框架核心内置的命令行框架。--hmr 标志监视文件系统并为代码库的某些部分执行热模块替换 (HMR)。

sh
node ace serve --hmr

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

构建生产版本 ​

由于 AdonisJS 应用程序是用 TypeScript 编写的，它们必须在生产环境中运行之前编译为 JavaScript。

你可以使用 node ace build 命令创建 JavaScript 输出。JavaScript 输出写入 build 目录。

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

另请参阅：TypeScript 构建过程。

sh
node ace build

配置开发环境 ​

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

我们强烈建议你使用 ESLint 来检查代码，使用 Prettier 重新格式化代码以保持一致性。

官方入门套件预配置了 ESLint 和 Prettier，并使用 AdonisJS 核心团队的有主见预设。你可以在文档的工具配置部分了解更多信息。

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

sh
# 运行 ESLint
npm run lint

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

# 运行 prettier
npm run format

VSCode 扩展 ​

你可以在任何支持 TypeScript 的代码编辑器上开发 AdonisJS 应用程序。但是，我们为 VSCode 开发了几个扩展来进一步增强开发体验。

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

  • Edge - 通过语法高亮、自动完成和代码片段支持来增强你的开发工作流程。

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