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"