Hbuilder X4.65新建vue3项目存在的问题以及解决办法

有关Vue的多篇文章：

1.使用Vue创建前后端分离项目的过程：使用Vue创建前后端分离项目的过程（前端部分）_vue前端项目打包的dish-CSDN博客

2.vue3实现自定义导航菜单：vue3实现自定义导航菜单_vue3 导航栏-CSDN博客

3.Vue 3中实现多个自定义组件之间的切换：Vue 3中实现多个自定义组件之间的切换_vue3动态切换组件-CSDN博客

4.在Vue3项目中引入省市区联动插件：在Vue3项目中引入省市区联动插件_piaoyi-citypicker-CSDN博客

5.在Vue2项目中引入时间区间插件：在Vue2项目中引入时间区间插件_vue2时间选择控件-CSDN博客

6.Vue2自定义注册和登录组件并实现在页面中切换：Vue2自定义注册和登录组件并实现在页面中切换_vue2自定义组件-CSDN博客

1.创建项目并构建

使用Hbuilder X4.65新建一个基于vue3的普通项目。

等待创建，创建完成后（会在右下角有通知），点击运行，选择"npm run build"构建项目。

选择"使用外部终端"。

2.问题提示即解决思路

之后会自动打开命令行工具，此时，会提示一些问题。

此时提示了如上问题：

翻译结果为：从vite.config.js文件加载配置失败。

具体原因是：Error [ERR_REQUIRE_ESM]: require() of ES Module file:///D:/HBuilderProjects/chapter4/node_modules/vite/dist/node/index.js not supported.

这说明在项目中某个地方使用了CommonJS的`require`来导入ES模块，而Vite现在默认使用ESM，导致不兼容。

其他问题："config must export or return an object"，即配置文件必须导出一个配置对象。是同样的错误，采用相同的办法处理。

原因为：混合使用了<script setup>和选项式API语法，这是冲突根源。<script setup>是 Vue 3的组合式API语法糖，不能与export default {}选项式API混合使用，同时包含这两种语法导致冲突。同时，在<script setup>语法中，导入的组件会自动注册，无需在components选项中手动注册。

可能的解决步骤：

（1）检查`vite.config.js`文件 ：确保它使用ESM的`import/export`语法，而不是CommonJS的`require/module.exports`。Vite的最新版本可能强制要求ESM，所以任何CommonJS语法都会导致错误。

（2）确认`package.json`中的type字段 ：如果存在`"type": "module"`，则Node.js会将该项目的所有.js文件视为ES模块。但Vite通常不需要这个，因为配置文件本身应使用ESM。

（3）检查Node.js版本：电脑可能安装了较旧的Node版本，而Vite需要较高的版本（如14.18+或16+）。可能需要升级Node.js。

（4）重新安装依赖：删除`node_modules`和`package-lock.json`后重新安装，确保所有依赖都是兼容ESM的版本。

（5）检查HBuilder X的项目模板：可能最新版的HBuilder X使用的模板存在配置问题，需要手动调整配置文件。

（6）查看Vite的更新日志：可能Vite的最新版本有破坏性变更，导致原有配置方式失效，需调整配置写法。

可能用户在电脑上安装的环境不同，比如Node版本较低，或者HBuilder X的模板没有正确生成ESM格式的配置文件。例如，`vite.config.js`如果使用了`module.exports = {...}`而不是`export default defineConfig({...})`，就会触发此错误。这个后面会进行验证。

3.问题解决步骤

经以上分析，可知，这是由Node.js环境与Vite的ESM模块规范冲突导致的问题。以下是分步解决方案：

问题根源分析 ：

错误 ERR_REQUIRE_ESM 表明你的环境尝试用CommonJS的require()加载ESM模块，而 Vite 4+ 默认要求使用ES Modules (ESM)。这通常由以下原因引起：

（1）Node.js 版本过低（需 v14.18+ 或更高）

（2）vite.config.js 未使用 ESM 语法

（3）项目依赖安装异常

完整解决方案 ：

（1）步骤 1：升级 Node.js

要求版本：Node.js ≥ 16.0.0

Node.js官网下载：Node.js --- 在任何地方运行 JavaScript

# 验证版本

node -v

# 输出应为 v16.x 或更高

（2）步骤 2：修正vite.config.js配置

确保配置文件使用ESM语法（而非 CommonJS）：

检查 vite.config.js 文件，打开项目根目录下的 vite.config.js，确保它导出了一个有效的配置对象。一个基本的Vue 3项目的ESM语法的Vite配置通常具有以下结构，vite.config.js文件的javascript代码如下（这个地方，正常来说是没有问题的）：

// vite.config.js

import { defineConfig } from 'vite'

import vue from '@vitejs/plugin-vue'



export default defineConfig({

  plugins: [vue()]

})

如果没有 defineConfig 和 @vitejs/plugin-vue，请确保安装了依赖（CMD命令）：

npm install --save-dev @vitejs/plugin-vue

或是直接打开项目根目录下的node_modules目录，看目录下是否有@vitejs。

验证文件格式。确保vite.config.js是标准的ES Module文件（ESM使用import/export语法），而不是CommonJS（require/module.exports）。如果误写为CommonJS语法，Vite可能无法正确解析。

（3）步骤 3：清理缓存并重装依赖

Cmd中执行以下命令：

# 进入项目目录

cd D:\HBuilderProjects\chapter4

# 删除旧依赖

rm -rf node_modules package-lock.json

# 重新安装（使用 npm 或 yarn）

npm install

如果不会执行CMD命令，当然也可以直接在Hbuilder X中进行删除，即删除node_modules目录和package-lock.json文件。

删除之后，再重新安装。点击如下"执行"按钮。

下面会有一个"npm install"安装命令。之后会调用命令行工具进行安装，项目目录中会重新出现node_modules目录和package-lock.json文件。

（4）步骤 4：检查项目配置（没有问题可以跳过）

在package.json中确保没有"type": "module"字段（Vite 项目不需要此配置）

确保没有混用 CommonJS 语法（如 require() 或 module.exports）

（5）步骤 5：验证Hbuilder X项目模板（没有问题可以跳过）

如果问题持续，可能是Hbuilder X的Vue3模板存在兼容性问题。可手动初始化 Vite 项目，CMD命令如下：

npm create vite@latest my-project -- --template vue

4. 附加配置建议

在 package.json 中添加以下脚本确保环境兼容性：

{

  "scripts": {

    "dev": "vite",

    "build": "vite build",

    "preview": "vite preview"

  },

  "type": "module" // 仅在明确需要时添加

}

常见问题排查表

|--------------|----------------|
| 现象 | 解决方案 |
| 旧 Node.js 版本 | 升级到 Node 16+ |
| require() 残留 | 全局搜索替换为 import |
| 依赖安装中断 | 清理缓存后重装依赖 |
| Windows 路径问题 | 检查路径是否含中文/特殊字符 |

完成上述步骤后，重新运行"npm run build"即可正常构建。如果出现如下结果，证明项目就成功了。

接下来继续运行"npm run dev"，如下结果表示可以正常访问了。

在浏览器中，打开http://localhost:3000/。

如果问题仍然存在，建议检查控制台完整错误日志或提供 vite.config.js 完整内容进一步分析。

5. ESM与ES的区别

ESM是指ECMAScript Modules，也就是ES模块系统，而ES通常指的是ECMAScript标准本身，比如ES6、ES2015等。

ES与ESM是包含与被包含的关系。以下是它们的核心区别对比

|------|-------------------------------|------------------------|
| 特性 | ES (ECMAScript) | ESM (ES Modules) |
| 定义 | JavaScript 语言标准（如 ES6/ES2015） | ES 标准中定义的模块系统规范 |
| 范围 | 包含语言所有特性（变量、函数、类等） | 专注于模块导入/导出机制 |
| 语法 | let/const, 箭头函数, class 等 | import/export |
| 出现时间 | 持续演进（ES5、ES6、ES2023等） | 正式成为标准在 ES6 (2015) |
| 依赖环境 | 所有 JavaScript 运行环境 | 需环境支持模块系统（浏览器/Node.js） |

示例对比

示例 1：ES基础特性（箭头函数 + 解构）

javascript代码示例：

// ES 特性（ES6+）

const sum = (a, b) => a + b; // 箭头函数

const [x, y] = [1, 2];        // 解构赋值

class Person {}                // 类语法

示例 2：ESM 模块系统

javascript代码示例：

// math.js（模块导出）

export const PI = 3.1415926;

export function circleArea(r) {

  return PI * r ** 2;

}



// app.js（模块导入）

import { PI, circleArea } from './math.js';

console.log(circleArea(2)); // 输出 12.5663704

关键区别详解

（1）ES是语言基础

包含JavaScript的所有核心语法

示例特征：

// ES6 特性

const obj = { a: 1, b: 2 };

const { a, b } = obj;  // 解构赋值



// ES2020 特性

const result = await fetch(url); // Top-level await

（2）ESM是模块化方案

专门解决代码组织问题

示例场景：

// 导出默认模块

export default function() {

  console.log('默认导出');

}



// 动态导入（ES2020）

const module = await import('./module.js');

环境支持差异

|----------------|-------|---------------------------|
| 环境 | ES支持 | ESM支持 |
| 现代浏览器 | 大部分特性 | 需<script type="module"> |
| Node.js | 依赖版本 | 需.mjs扩展名或package.json配置 |
| Webpack/Rollup | 自动转换 | 原生支持 |

混合使用示例

html

<script type="module">

  // ESM 模块

  import { version } from './config.js';

  

  // ES 特性

  const log = (msg) => console.log(`[${version}] ${msg}`);

  

  class App {

    constructor() {

      log('初始化完成');

    }

  }

  

  new App();

</script>

树状关系

ECMAScript (ES)

├── 基础语法（变量、函数、类）

├── 内置对象（Array、Promise）

├── ESM（模块系统）

└── 其他特性（Proxy、Decorators等）

6.ESM与CJS的区别

在Vue项目中，ES Modules (ESM)和CommonJS (CJS) 是两种不同的JavaScript模块规范，它们的核心区别对比：

|--------------|--------------------|------------------------|
| 特性 | ES Modules (ESM) | CommonJS (CJS) |
| 语法 | import/export | require/module.exports |
| 加载方式 | 静态编译（编译时解析） | 动态加载（运行时解析） |
| 模块类型 | 官方标准（ES6+） | Node.js传统规范 |
| 文件扩展名 | .mjs 或 .js（需配置） | .cjs 或 .js（默认） |
| 浏览器支持 | 原生支持（现代浏览器） | 需打包工具转换（如webpack） |
| Tree Shaking | 支持（静态分析） | 不支持（需工具辅助） |
| Vue官方推荐 | Vue 3 + Vite项目默认规范 | Vue CLI 旧项目可能使用 |

在 Vue 中的具体使用场景

（1）Vue单文件组件（.vue文件）

强制使用ESM：Vue的<script setup>和常规 <script>标签默认使用ESM语法，混合使用会报错。

（2）配置文件差异

|----------------|-----------------|-----------------|
| 文件 | ESM写法 | CJS写法 |
| vite.config.js | 必须使用ESM | 不支持 |
| vue.config.js | 支持（需Node 13.2+） | 传统Vue CLI项目默认使用 |

（3）组件/工具库开发

javascript代码示例：

// ESM 写法（推荐）

import { ref } from 'vue'

export const count = ref(0)



// CJS 写法（旧项目兼容）

const vue = require('vue')

exports.count = vue.ref(0)

如何选择？

|-----------------|---------------|
| 场景 | 推荐规范 |
| Vue 3 + Vite新项目 | 强制ESM |
| Vue CLI 旧项目 | CJS兼容 |
| 开发组件库（需跨环境兼容） | 同时提供ESM/CJS打包 |
| Node.js 服务端集成 | 根据环境配置（推荐ESM） |

最佳实践建议

（1）Vue 3项目：全面使用ESM + <script setup>

（2）旧项目迁移：逐步将require改为import

（3）工具库开发：使用构建工具（如 Rollup）同时生成ESM/CJS包

（4）Node.js环境：升级到14+版本，在 package.json添加 "type": "module"