IntelliJ IDEA 2025.3 Help

Next.js

IntelliJ IDEA 与 Next.js React 框架集成。

开始之前

  1. 下载并安装 Node.js

  2. 确保 JavaScript 和 TypeScript 以及 Next.js Support 必需插件在 设置 | 插件 页面, 已安装 选项卡上已启用。 如需更多信息,请参阅 管理插件

创建新的 Next.js 应用程序

推荐开始构建新的 Next.js 应用程序的方法是 create-next-app 包,该包使用 npx 为您IntelliJ IDEA下载和运行。 因此,您的开发环境已预配置为使用 Next.js。

当然,您仍然可以自行下载 create-next-app 或者创建一个空的 IntelliJ IDEA 项目并在其中安装 Next.js。

使用 create-next-app 生成 Next.js 应用程序

  1. 从主菜单中选择 文件 | 新建 | 项目 ,或者在 欢迎 屏幕上单击 新建项目 按钮。

  2. 新建项目 对话框的左侧窗格中,选择 React

  3. 在向导的右侧部分,指定项目名称和创建该项目的文件夹。

  4. 项目类型 区域,选择 Next.js

    Node.js 运行时 字段中,指定要使用的 Node.js 运行时。 从列表中选择一个已配置的运行时,或选择 添加 以配置新的运行时。

    create-next-app 列表中选择 npx create-next-app

    或者,对于 npm 版本 5.1 及更早版本,请在 终端 Alt+F12 中运行 npm install --save-dev next react react-dom ,自行安装 create-next-app 包。 创建应用程序时,选择存储 create-next-app 包的文件夹。

  5. 可选:

    若要使用 TypeScript 而非 JavaScript,请选中 使用 TypeScript 模板 复选框。 IntelliJ IDEA 将为您的应用生成 .ts 文件以及一个 tsconfig.json 配置文件。

  6. 当您点击 创建 时,IntelliJ IDEA 会生成一个 Next.js 特定项目,其中包含所有必需的配置文件并下载所需的依赖项。 IntelliJ IDEA 还会创建一个 npm startJavaScript Debug 配置,使用默认设置来运行或调试您的应用程序。

在空的 IntelliJ IDEA 项目中安装 Next.js

在这种情况下,您需要自行配置构建流水线。 从 Next.js 官方网站了解更多关于将 Next.js 添加到项目中的信息。

创建一个空的 IntelliJ IDEA 项目

  1. 从主菜单中选择 文件 | 新建 | 项目 ,或者在 欢迎 屏幕上单击 新建项目 按钮。

  2. 新建项目 对话框的左侧窗格中,选择 新建项目

  3. 在右侧窗格中,选择 JavaScript语言 区域。

  4. 为新项目命名,并在必要时更改其位置,然后单击 创建

在空项目中安装 Next.js

  1. 打开您将使用 Next.js的空项目。

  2. 在内置的 终端Alt+F12 )中,输入:

    npm install --save-dev next react react-dom

从现有的 Next.js 应用程序开始

要继续开发现有的 Next.js 应用程序,请在 IntelliJ IDEA 中打开它并下载所需的依赖项。

打开您计算机上已有的应用程序源代码

  • 点击 打开或导入 屏幕上的 欢迎 或从主菜单中选择 文件 | 打开。 在打开的对话框中,选择存储源文件的文件夹。

从您的版本控制系统检出应用程序源代码

  1. 欢迎 屏幕上单击 克隆存储库

    或者,从主菜单中选择 文件 | 新建 | 来自版本控制的项目…Git | 克隆…VCS | 从版本控制获取

    在主菜单中,您可能会看到与您的项目关联的其他任何版本控制系统,而不是 Git。 例如, MercurialPerforce

  2. 在打开的对话框中,从列表中选择您的版本控制系统,并指定要从中检出应用程序源代码的存储库。 有关更多信息,请参阅 检出项目(克隆)

下载依赖项

  • 在弹出窗口中点击 运行 'npm install'运行 'yarn install'

    打开应用程序并下载依赖项

    您可以使用 npmYarn 1Yarn 2 ,详情请参阅 npm 和 Yarn

  • 或者,在编辑器中或在 项目 工具窗口 Alt+1 中,从 package.json 的上下文菜单中选择 运行 'npm install'运行 'yarn install'

项目安全

当您打开一个在 IntelliJ IDEA 外部创建并导入到其中的项目时,IntelliJ IDEA 会显示一个对话框,您可以在其中决定如何处理包含不熟悉的源代码的项目。

请选择以下选项之一:

  • 在安全模式中预览 :在这种情况下,IntelliJ IDEA 以预览模式打开项目。 这意味着您可以浏览项目的源代码,但无法运行任务和脚本,也无法运行或调试您的项目。

    IntelliJ IDEA 会在编辑器区域顶部显示一条通知,您可以点击 信任项目… 链接,随时加载您的项目。

  • 信任项目 :在这种情况下,IntelliJ IDEA 会打开并加载一个项目。 这意味着项目已初始化,项目的插件已解析,依赖项已添加,并且所有 IntelliJ IDEA 功能均可用。

  • 不打开 :在这种情况下,IntelliJ IDEA 不会打开项目。

有关更多信息,请参阅 项目安全

运行和调试 Next.js 应用程序

使用 IntelliJ IDEA,您可以通过两种方式运行您的应用程序并开始调试会话:

  • 从编辑器 - 以脚本形式从 package.json 或在 终端 中运行 next dev 命令。 然后通过点击 运行 工具窗口或 终端 中的应用程序 URL 开始调试会话。

  • 使用运行/调试配置

从编辑器开始运行和调试

使用 next dev 运行一个应用程序

  1. package.json 中,在 dev 脚本旁的边距中点击 运行图标 ,或在 终端 中的 Alt+F12 执行 next dev 命令,或在 npm 工具窗口查看 | 工具窗口 | npm )中双击 dev 任务。

    从 package.json 运行 next dev
  2. 请等待应用编译完成且开发服务器就绪。

    运行 工具窗口或 终端 显示了应用程序运行的 URL,默认 URL 是 http://localhost:3000

    运行工具窗口,带有指向应用程序的链接

    点击此链接以在浏览器中查看应用程序。

从运行工具窗口或终端开始调试会话

  1. 设置断点 (如有必要)。

  2. package.json 中,在 dev 脚本旁的边距中点击 运行图标 ,或在 终端 中的 Alt+F12 执行 next dev 命令,或在 npm 工具窗口查看 | 工具窗口 | npm )中双击 dev 任务。

  3. 请等待应用编译完成且开发服务器就绪。

    运行 工具窗口或 终端 显示了应用程序运行的 URL,默认 URL 是 http://localhost:3000

    从运行工具窗口开始调试会话

    按住 Ctrl+Shift 并点击链接。

  4. 当应用程序在浏览器中打开时,执行触发程序运行的操作,例如点击链接。 焦点切换到 IntelliJ IDEA,并打开 调试工具窗口

    调试会话已启动

    照常进行: 逐步执行程序暂停并恢复程序执行, 在暂停时检查程序 ,探索调用堆栈与变量,设置监视,计算变量值, 查看实际的 HTML DOM ,等等。

使用运行/调试配置运行和调试一个 Next.js 应用程序

当您打开一个在根目录 package.json 中列为依赖项的 next 包的单一存储库项目时,IntelliJ IDEA 会自动生成两个运行/调试配置:

  • Next.js:服务器端 ,类型为 npm。 该配置执行 next dev 命令,启动开发服务器并以开发模式运行您的应用程序。

  • Next.js:调试客户端 ,类型为 JavaScript Debug ,用于在浏览器中调试您的应用程序。

生成了两个运行/调试配置

创建运行/调试配置

  1. 前往 运行 | 编辑配置。 或者,在工具栏上的 运行 小部件中选择 编辑配置

    打开编辑配置对话框

    在打开的 编辑配置 对话框中,点击工具栏上的 添加 按钮("添加"按钮 ),然后从列表中选择 npm

  2. 在打开的 配置 对话框的 运行/调试配置:npm 选项卡中,指定 package.json 、Node.js 运行时以及要使用的包管理器的位置。

    命令 字段中,从列表中选择 运行 ,然后在 脚本 列表中选择要运行的脚本。 它很可能是默认的 dev 脚本,但您也可以在 package.json 中配置其他脚本,例如在自定义端口上运行应用。

    npm 运行/调试配置
  3. 可选:

    要在浏览器中打开应用程序,请按照以下步骤更新配置:在 浏览器 / 实时编辑 选项卡中,选中 在启动后 复选框,选择要在其中打开应用程序的浏览器,并指定应用程序将运行的 URL 地址。

    Browser / Live Edit 选项卡:选择浏览器

使用 npm 运行/调试配置以开发模式运行一个应用程序

  1. 从工具栏上的 运行 小部件列表中,选择一种 npm 类型的运行配置。 这可以是自动生成的 Next.js:服务器端 配置,或者是您自行创建的自定义配置 如上所述

    通过运行/调试配置以开发模式运行一个 Next.js 应用程序

    点击 运行图标

  2. 当应用程序编译完成并且开发服务器准备就绪时, 运行 工具窗口显示了应用程序运行的 URL。 默认 URL 是 http://localhost:3000 ,但如果默认端口 3000 已被占用,服务器会尝试在最近的空闲端口上启动。

    运行 Next.js 应用程序的开发模式:开发服务器已准备好

    单击此链接以查看应用。

    或者,启用 IntelliJ IDEA 以在启动时打开应用程序 如上所述

使用 JavaScript 调试配置开始调试

  1. 设置断点 (如有必要)。

  2. 在开发模式下运行您的应用程序 使用 npm 运行/调试配置使用 next dev

  3. 当应用程序编译完成并且开发服务器准备就绪时, 运行 工具窗口显示了应用程序运行的 URL。 默认 URL 是 http://localhost:3000 ,但如果默认端口 3000 已被占用,服务器会尝试在最近的空闲端口上启动。

  4. 从工具栏上的 运行 小部件列表中,选择一种 JavaScript 调试 类型的运行配置。 这可以是自动生成的 Next.js:调试客户端 配置,或者是您自行创建的自定义配置 如上所述

    开始调试会话 — 选择 JavaScript 调试运行配置

    点击 调试图标

  5. 当应用程序在浏览器中打开时,执行触发程序运行的操作,例如点击链接。 焦点切换到 IntelliJ IDEA,并打开 调试工具窗口

    照常进行: 逐步执行程序暂停并恢复程序执行, 在暂停时检查程序 ,探索调用堆栈与变量,设置监视,计算变量值, 查看实际的 HTML DOM ,等等。

请参阅 运行一个 React 应用程序调试一个 React 应用程序

最后修改日期: 2025年 12月 2日