WebStorm 2025.3 Help

Next.js

WebStorm 与 Next.js React 框架集成。

开始之前

  1. 请确保您的计算机上安装了 Node.js。

  2. 请确保在设置中已启用 Next.js Support 插件。 按 Ctrl+Alt+S 打开设置,然后选择 插件。 点击 已安装 选项卡。 在搜索字段中,输入 Next.js Support。 有关插件的更多信息,请参阅 插件管理。

创建新的 Next.js 应用程序

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

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

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

  1. 点击 新建项目 屏幕上的 欢迎 或从主菜单中选择 文件 | 新建 | 项目。 将打开 新建 项目 对话框。

  2. 在左侧窗格中,选择 Next.js。

  3. 在右侧窗格中:

    1. 指定将存储项目相关文件的文件夹路径。

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

    3. 从 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 包的文件夹。

    4. 可选:

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

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

在一个空的 WebStorm 项目中安装 Next.js

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

创建一个空的 WebStorm 项目

  1. 点击 新建项目 屏幕上的 欢迎 或从主菜单中选择 文件 | 新建 | 项目。 将打开 新建 项目 对话框。

  2. 在左侧窗格中,选择 空项目。 在右侧窗格中,指定应用程序文件夹并点击 创建。

在空项目中安装 Next.js

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

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

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

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

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

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

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

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

  1. 在 欢迎 屏幕上点击 克隆仓库。

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

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

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

下载依赖项

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

    打开应用并下载依赖项

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

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

项目安全性

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

不受信任的项目警告

请选择以下选项之一:

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

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

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

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

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

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

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

  • 从编辑器 - 以脚本形式从 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. 当应用程序在浏览器中打开时,执行触发程序运行的操作,例如点击链接。 焦点切换到 WebStorm,并打开 调试工具窗口。

    调试会话已启动

    按常规操作: 逐步执行程序、 停止并恢复程序执行、 在暂停时检查程序 ,探索调用堆栈和变量,设置监视,评估变量, 查看实际的 HTML DOM 等。

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

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

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

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

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

创建运行/调试配置

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

    打开“Edit Configurations”对话框

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

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

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

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

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

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

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

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

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

    点击 运行图标。

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

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

    点击此链接以查看应用。

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

使用 JavaScript 调试配置开始调试

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

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

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

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

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

    点击 调试图标。

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

    按常规操作: 逐步执行程序、 停止并恢复程序执行、 在暂停时检查程序 ,探索调用堆栈和变量,设置监视,评估变量, 查看实际的 HTML DOM 等。

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

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