基于Node.js Fastify启动Webpack Dev Server报错及调试咨询

一、核心错误分析 #

报错AvvioError [Error]: Plugin must be a function or a promise. Received: 'object'的本质是：Fastify尝试加载的插件（包括autoload目录下的插件或入口bundle.js导出内容）不符合要求——必须是函数或返回Promise的函数，而非普通对象。

二、分步解决启动问题 #

1. 修正Fastify启动命令 #

原命令中--options参数误用，该参数用于传递配置JSON文件，而非指定入口脚本。修改package.json中的启动命令：

"start": "fastify start -l debug dist/bundle.js"

2. 调整Webpack配置（适配Node.js环境） #

Webpack的devServer是为浏览器端开发服务的，Node.js环境下无需配置，同时优化热更新与打包逻辑：
修改webpack.development.js：

const merge = require('webpack-merge');
const nodeExternals = require('webpack-node-externals');
const path = require('path');
const webpack = require('webpack');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

const common = require('./webpack.common.js');

module.exports = merge.smart(common, {
  devtool: 'inline-source-map',
  entry: ['webpack/hot/poll?1000', path.join(__dirname, 'src/app.ts')],
  externals: [
    nodeExternals({
        allowlist: ['webpack/hot/poll?1000']
    })
  ],
  // 移除devServer配置，添加watch模式支持
  watch: true,
  mode: 'development',
  plugins: [new CleanWebpackPlugin(), new webpack.HotModuleReplacementPlugin()]
});

3. 确保入口文件与插件的正确导出格式 #

• 入口文件src/app.ts：必须导出Fastify插件函数（或返回Promise的函数），示例：

import Fastify from 'fastify';
import AutoLoad from '@fastify/autoload';
import { join } from 'path';
import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';

// 导出Fastify插件函数
export default async function app(fastify, opts) {
  // 注册Autoload插件
  await fastify.register(AutoLoad, {
    dir: join(__dirname, 'plugins'),
    options: opts,
  });

  // 注册Apollo GraphQL及Playground
  await fastify.register(require('@as-integrations/fastify'), {
    plugins: [ApolloServerPluginLandingPageLocalDefault()],
    // 其他GraphQL配置...
  });
}

// 本地直接启动的逻辑（可选，用于不用fastify start的场景）
if (require.main === module) {
  const fastify = Fastify({ logger: { level: 'debug' } });
  fastify.register(app);
  fastify.listen({ port: 8080 }, (err) => {
    if (err) {
      fastify.log.error(err);
      process.exit(1);
    }
  });
}

• Autoload插件目录plugins/下的文件：每个插件必须导出符合要求的函数，禁止导出对象，示例：

// plugins/example-plugin.ts
export default async function examplePlugin(fastify, opts) {
  fastify.log.debug('加载example-plugin插件');
  // 插件业务逻辑...
}

三、Autoload插件调试方法 #

1. 启用详细日志 #

• 在Fastify实例中开启debug级别日志：

const fastify = Fastify({ logger: { level: 'debug' } });

• 启动时添加Avvio调试环境变量，获取插件加载的详细流程：

"start": "AVVIO_DEBUG=1 fastify start -l debug dist/bundle.js"

2. 代码级断点调试 #

使用Node.js Inspector进行断点调试，修改启动命令：

"start:debug": "node --inspect-brk node_modules/.bin/fastify start dist/bundle.js"

打开Chrome浏览器访问chrome://inspect，连接调试器后在Autoload注册处、插件文件中设置断点，逐步排查加载过程。

3. 插件合法性校验 #

在Autoload注册前，手动校验plugins目录下的文件导出格式，添加临时代码：

import { readdirSync, statSync } from 'fs';
import { join } from 'path';

const pluginsDir = join(__dirname, 'plugins');
readdirSync(pluginsDir).forEach(file => {
  const filePath = join(pluginsDir, file);
  if (statSync(filePath).isFile() && file.endsWith('.ts')) {
    const plugin = require(filePath);
    if (typeof plugin.default !== 'function') {
      console.error(`插件${file}导出格式错误，必须是函数`);
    }
  }
});

4. 排除插件逐个测试 #

临时注释Autoload注册，手动逐个注册plugins目录下的插件，定位导致错误的具体插件：

// 注释原Autoload
// await fastify.register(AutoLoad, { dir: join(__dirname, 'plugins'), options: opts });

// 手动逐个注册
await fastify.register(require('./plugins/plugin1.ts').default);
await fastify.register(require('./plugins/plugin2.ts').default);

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