PyCharm 2025.2 Help

Vite

PyCharm 与 Vite 构建工具集成,这提高了前端开发体验。 Vite 由开发服务器和构建命令组成。 构建服务器通过原生 ES 模块提供您的源文件。 构建命令将使用 Rollup 打包您的代码,经过预配置以输出高度优化的生产静态资源。

PyCharm 支持 tsconfig.json jsconfig.json 路径映射在 Vue style 标签中,识别 Vite aliases

在包含多个具有不同 Vite 配置的模块的项目中,PyCharm 可以自动检测每个模块的相关配置文件并使用该配置文件中的模块解析规则,请参阅下文的 指定要使用的 Vite 配置文件

在开始之前

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

  2. 请确保 JavaScript and TypeScriptVite 必需插件在 设置 | 插件 页面上的 已安装 选项卡中已启用。 如需了解更多信息,请参阅 管理插件

创建一个新的 Vite 应用程序

推荐开始一个新的 Vite 应用程序的方式是使用 create-vite 软件包,PyCharm 使用 npx 为您下载并运行。 因此,您的开发环境已预配置为使用 Vite 和一个流行框架的基本模板,例如 ReactVue.jsSvelte 等。

当然,您仍然可以自己下载 create-vite 或创建一个空的 PyCharm 项目并在其中安装 Vite。

使用 create-vite 生成 Vite 应用程序

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

  2. 在左侧窗格中,选择 Vite

  3. 在右侧窗格中:

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

    2. Node Interpreter 字段中,指定要使用的 Node.js 解释器。 从列表中选择一个已配置的解释器或选择 添加 配置一个新的解释器。

    3. 请从 Vite 列表中选择 npx create-vite

      或者,对于 npm 5.1 及更早版本,通过在 终端 Alt+F12 中运行 npm install --g create-vite 来自行安装 create-vite 包。 在创建应用程序时,选择存储 create-vite 包的文件夹。

    4. 模板 列表中,选择适用于您将要在应用程序中使用的框架的 community maintained Vite template

    5. 可选:

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

  4. 当您点击 创建 时,PyCharm 会生成一个 Vite 特定项目,包括所有必需的配置文件并下载所需的依赖项。 PyCharm 还会创建一个 npm dev 配置,使用默认设置运行您的应用程序。

在空的 PyCharm 项目中安装 Vite

在这种情况下,您将不得不自己配置 构建 pipeline。 有关将 Vite 添加到项目的更多信息,请参阅 Vite 官方网站

创建一个空的 PyCharm 项目

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

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

在空项目中安装 Vite

  1. 打开空的 项目,在这里您将使用 Vite

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

    npm install --save-dev vite

从现有的 Vite 应用程序开始

若要继续开发现有的 Vite 应用,请在 PyCharm 中打开,并下载所需的依赖项。

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

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

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

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

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

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

  2. 在打开的对话框中,从列表中选择您的版本控制系统,并指定要从中检出的应用程序源代码的存储库。 如需了解更多信息,请参见 Check out a project (clone)

下载依赖项

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

    打开应用并下载依赖项

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

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

项目安全性

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

不受信任的项目警告

请选择以下选项之一:

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

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

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

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

请从 项目安全 了解更多。

在 PyCharm 中配置 Vite

创建 Vite 配置文件

  • 根据您的项目结构创建一个或多个配置文件:在 项目 工具窗口 Alt+1 中选择一个父文件夹,然后从上下文菜单中选择 新建 | JavaScript 文件

    创建 Vite 配置文件

    可接受的名称是 vite.config.js / vite.config.ts vite.config.mjs vite.config.cjs

    您可以从 Vite 官方网站了解更多信息。

  • 如果必要,请使用 alias ,该代码将在 import 语句中被识别。 确保在定义别名时指定绝对路径。 了解更多信息,请访问 Vite 官方网站

    在 import 语句中完成 alias

指定要使用的 Vite 配置文件

基于对 Vite 配置文件的分析,PyCharm 理解 Vite 配置,解析模块,并在 JavaScript 和 TypeScript 文件中提供编码帮助。

在 PyCharm 中,您可以选择两种配置模式——自动和手动。

通过 自动配置 ,PyCharm 会自动检测每个 JavaScript 或 TypeScript 文件的相关 Vite 配置文件。

您可以通过 手动配置指定项目中要使用的 Vite 配置文件。 如果您的 Vite 配置文件名未被 PyCharm 识别,手动配置是有用的,请参阅下方的 已识别 Vite 配置名称列表

选择如何检测 Vite 配置

  1. 打开 设置 对话框(Ctrl+Alt+S ),然后转到 语言与框架 | JavaScript | Vite

  2. 检测 Vite 配置文件以进行模块解析 区域,选择以下选项之一:

    • 自动: 在这种模式下,对于 JavaScript 或 TypeScript 文件,PyCharm 将首先在此 JavaScript 或 TypeScript 文件所在的文件夹中查找 Vite 配置文件,然后在其父文件夹中查找,以此类推。

      因此,如果您的项目包含多个具有不同 Vite 配置的模块,每个模块将使用其自己的 Vite 配置文件中的模块解析规则(如果找到此类配置)。

      PyCharm 能识别以下名称及顺序的 JavaScript 或 TypeScript Vite 配置文件:

      • vite.config.js vite.config.ts

      • vite.config.mjs

      • vite.config.cjs

    • 手动:配置文件 字段中,指定要使用的 Vite 配置的位置。

      在这种模式下,指定配置文件中的解析规则将应用于项目中的所有模块。

      如果您的 Vite 配置文件名称未被 PyCharm 识别,请参阅上面的 已识别的 Vite 配置名称列表

      请手动选择 vite 配置文件

运行 Vite 应用

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

    从 package.json 在开发模式下运行 Vite 应用
  2. 等待应用程序编译完成并且开发服务器准备就绪。

    运行 工具窗口或 终端 显示您的应用程序正在运行的 URL。 如果您的应用是使用 create-vue 生成的,默认 URL 是 http://localhost:5173/ 。 点击此链接查看应用程序。

    Vue.js 应用程序正在开发模式下运行

通过运行/调试配置运行 Vite 应用程序

对于在 PyCharm 新项目 向导中使用 create-vite 创建的应用 如上所述 ,PyCharm 会生成一个默认名称为 npm devnpm 配置。 此配置运行 vite 命令,用于启动开发服务器并在开发模式下启动您的应用程序。

在其他情况下,您需要手动 创建一个运行/调试配置 ,并设置实际的参数,如主机、端口等。

创建一个 npm 运行/调试配置

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

    打开“Edit Configurations”对话框

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

  2. 在弹出的 配置 选项卡 运行/调试 配置:npm 对话框中,指定 package.json 的位置、Node.js 解释器及要使用的软件包管理器。

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

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

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

    如果您要调试应用程序,请选择 Google Chrome 或另一个 Chromium-based browser

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

运行应用程序

  1. 从工具栏的列表中选择 npm dev 运行配置,然后点击其旁边的 运行

    通过运行/调试配置在开发模式下运行 Vite 应用
  2. 等待应用程序编译完成并且开发服务器准备就绪。

    运行 工具窗口或 终端 显示您的应用程序正在运行的 URL。 点击此链接查看应用程序。

    正在运行 Vite 应用:开发服务器已准备就绪

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

调试 Vite 应用程序

您可以通过 启动运行/调试配置从运行工具窗口 ,该窗口显示您的应用程序在开发模式下运行的 URL,开始调试会话。

通过运行/调试配置开始调试

要调试您的 Vite 应用程序,您需要两个运行/调试配置:

  • 在开发模式下启动应用程序的 npm 配置, 如上所述

  • 开发模式下附加调试器到正在运行的应用程序的 JavaScript 调试 配置。

您可以在 JavaScript 调试 配置中创建 npm 配置,以便按照 使用 npm run/debug 配置运行和调试 Vite 应用程序 中所述一起启动它们。

或者,分别创建并启动 npmJavaScript 调试 运行/调试配置,如 使用 JavaScript 调试运行/调试配置开始调试 中所述。

使用单个 npm run/debug 配置运行和调试 Vite 应用程序

  1. 在您的代码中设置 breakpoints

  2. 创建一个 npm 配置 如上所述

    如果您使用 create-vite 生成了应用程序,PyCharm 已经使用默认名称 npm dev 创建了一个 npm 配置。 此配置可通过 运行 小部件或 运行/调试配置 对话框获得。

    自动生成的 npm run/debug 配置
  3. 在弹出的 配置 选项卡 运行/调试 配置:npm 对话框中,指定 package.json 的位置、Node.js 解释器及要使用的软件包管理器。

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

    npm 运行/调试配置
  4. 浏览器 / 实时编辑 选项卡中,选中 启动后 复选框,从列表中选择 Google Chrome 或其他 Chromium-based browser ,选中 使用 JavaScript 调试器 复选框,然后指定您的应用程序将运行的 URL。

    npm 配置,浏览器标签
  5. 点击 运行

    要重新运行配置,请从 运行 小部件中的列表中选择,然后点击其旁边的 运行

    PyCharm 在开发模式下运行应用程序,同时启动调试会话。

    调试会话
  6. 当第一个断点被触发时,切换到 调试工具窗口 并像往常一样继续: 逐步执行程序停止和恢复程序执行、 在暂停时检查 、探索调用堆栈和变量、设置监视、评估变量、 查看实际的 HTML DOM 等。

使用 JavaScript Debug 运行/调试配置开始调试

  1. 在您的代码中设置 breakpoints

  2. 启动应用程序的开发模式 ,如上所述 ,并等待应用程序编译完成以及开发服务器就绪。

    运行 工具窗口或 终端 显示您的应用程序正在运行的 URL。 请复制此 URL 到 稍后在 JavaScript Debug 配置中指定

    应用程序正在开发模式下运行
  3. 创建一个 JavaScript 调试 配置。 要执行此操作,请在主菜单中转到 运行 | 编辑配置 ,点击 "添加"图标 ,然后从列表中选择 Javascript 调试

  4. 在打开的 运行/调试配置:JavaScript Debug 对话框中,指定配置的名称以及应用程序在开发模式下运行的 URL 地址。 您可以在 运行 工具窗口或 终端 中复制此 URL, 如上所述

    创建一个 JavaScript 调试配置:指定 URL
  5. 点击 调试

    要重新运行配置,请从 运行 小部件中的列表中选择,然后点击其旁边的 调试

    从运行小部件运行 JavaScript Debug 配置
  6. 当第一个断点被触发时,切换到 调试工具窗口 并像往常一样继续: 逐步执行程序停止和恢复程序执行、 在暂停时检查 、探索调用堆栈和变量、设置监视、评估变量、 查看实际的 HTML DOM 等。

从 Run 工具窗口或内置 Terminal 开始调试

如果您的应用程序正在 localhost 上运行开发模式,特别是如果它是用 create-vite 生成的,您可以直接从 >运行 工具窗口或内置的 终端 启动调试会话。

  1. 在您的代码中设置 breakpoints

  2. 启动应用程序的开发模式 ,如上所述 ,并等待应用程序编译完成以及开发服务器就绪。

  3. 运行 工具窗口或 终端 显示您的应用程序正在运行的 URL。 按住 Ctrl+Shift 并点击此 URL 链接。 PyCharm 启动带有 类型 JavaScript Debug的自动生成配置的调试会话。

    从运行工具窗口启动调试会话,应用程序正在 localhost 上运行

    如果您从 New Terminal 以开发模式启动了应用程序,您只需点击链接旁边的 在浏览器中开始调试 按钮即可。

    新终端:在浏览器中开始调试按钮

当第一个断点被触发时,切换到 调试工具窗口 并像往常一样继续: 逐步执行程序停止和恢复程序执行、 在暂停时检查 、探索调用堆栈和变量、设置监视、评估变量、 查看实际的 HTML DOM 等。

针对 Node.js 17+ 的故障排除

如果您使用的是 Node.js 版本 17 或更高版本,在调试过程中,您可能会遇到网络连接问题,这会导致调试器附加或者加载 sourcemaps 时出现问题。

解决方法是将 --host 127.0.0.1 传递给服务器。 您可以通过以下方式之一来实现:

  • 在您的 dev 脚本中更新 package.json

    "dev": "vite --host=127.0.0.1"
  • 或者,添加 dns.setDefaultResultOrder('ipv4first') 到您的 vite.config.ts

最后修改日期: 2025年 9月 26日