Node全栈项目中mysql模块require未定义错误排查求助

问题根源 #

你核心的问题是把后端数据库连接代码错误打包到了前端浏览器环境的bundle中：

• mysql是Node.js专属的CommonJS模块，依赖crypto、events等Node内置模块，这些在浏览器环境中完全不存在
• 浏览器本身不支持Node的require语法，即便打包时添加--platform=node，前端运行时依然会因无法识别require报错

解决方案 #

1. 严格拆分前后端代码 #

将项目明确划分为两个独立部分：

• 前端代码：仅处理页面交互、API请求等浏览器端逻辑，绝对不包含数据库连接相关代码
• 后端代码：负责启动Express服务、数据库连接、API接口处理等Node端逻辑

2. 调整项目结构 #

示例结构：

your-project/
├── src/
│   ├── client/          # 前端代码目录
│   │   └── app.ts       # 前端交互逻辑
│   └── server/          # 后端代码目录
│       ├── db.ts        # 数据库连接逻辑
│       └── server.ts    # Express服务启动文件
├── index.html
└── package.json

3. 编写拆分后的代码 #

后端数据库连接（src/server/db.ts）

import mysql from 'mysql';

const config = {
  user: '你的数据库用户名',
  password: '你的数据库密码',
  host: '数据库地址',
  database: '目标数据库名',
  port: 3306
};

// 创建数据库连接
export function initDbConnection() {
  const connection = mysql.createConnection(config);
  connection.connect((err) => {
    if (err) {
      console.error('数据库连接失败:', err);
      return;
    }
    console.log('数据库连接成功');
  });
  return connection;
}

后端Express服务（src/server/server.ts）

import express from 'express';
import { initDbConnection } from './db';
import path from 'path';

const app = express();
const port = 3000;

// 初始化数据库连接
initDbConnection();

// 托管前端静态资源
app.use(express.static(path.join(__dirname, '../../dist/client')));

// 返回首页
app.get('/', (req, res) => {
  res.sendFile(path.join(__dirname, '../../index.html'));
});

// 示例API接口
app.get('/api/test', (req, res) => {
  res.json({ message: '后端API正常响应' });
});

app.listen(port, () => {
  console.log(`服务运行在 http://localhost:${port}`);
});

前端代码（src/client/app.ts）

// 仅编写浏览器端逻辑，比如请求后端API
async function fetchApiData() {
  try {
    const res = await fetch('/api/test');
    const data = await res.json();
    console.log(data);
  } catch (err) {
    console.error('API请求失败:', err);
  }
}

fetchApiData();

4. 调整打包命令 #

前端打包（浏览器环境）

无需--platform=node，打包时自动适配浏览器：

esbuild src/client/app.ts --bundle --minify --sourcemap --outfile=dist/client/bundle.js

后端打包（Node.js环境）

添加--platform=node，并将第三方模块标记为外部依赖（保留原CommonJS格式，避免打包冲突）：

esbuild src/server/server.ts --platform=node --external:mysql --external:express --bundle --minify --sourcemap --outfile=dist/server/server.js

5. 配置package.json脚本 #

{
  "type": "module",
  "scripts": {
    "build:client": "esbuild src/client/app.ts --bundle --minify --sourcemap --outfile=dist/client/bundle.js",
    "build:server": "esbuild src/server/server.ts --platform=node --external:mysql --external:express --bundle --minify --sourcemap --outfile=dist/server/server.js",
    "build": "npm run build:client && npm run build:server",
    "start": "node dist/server/server.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "mysql": "^2.18.1"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/mysql": "^2.15.26",
    "@types/node": "^20.10.5",
    "esbuild": "^0.19.10"
  }
}

内容的提问来源于stack exchange，提问作者Steven Shoemaker