Nuxt构建报错：appendHeader is not defined 排查与解决

问题概述 #

项目在npm run dev开发模式下运行正常，但执行npm run build生产构建时，抛出appendHeader is not defined错误，控制台同时出现TailwindCSS源映射警告、Nitro相关警告。环境配置为Node.js v22.12.0，基于Nuxt框架开发。

排查过程 #

1. 最初怀疑是新增的Leaflet地图功能引发依赖或配置冲突，排查相关组件、依赖版本及配置后未发现异常
2. 逐步排查项目文件，最终定位到frontend/server/api/routes.ts文件，移除该文件后构建成功

问题分析与修复建议 #

appendHeader是Nuxt/Nitro服务器端API的专属方法，用于在服务器路由中设置响应头。出现该错误的核心原因通常是：

• routes.ts中调用appendHeader时未正确获取Nuxt服务器上下文（比如未在路由处理函数的参数中解构上下文，或在非服务器上下文环境中调用该方法）
• 文件内容不符合Nuxt服务器API的规范（比如导出的路由结构错误，或使用了过时的API写法）

修复方案：

• 若该文件为业务所需，检查代码并修正为符合Nuxt服务器API的写法，示例正确结构：

export default defineEventHandler((event) => {
  appendHeader(event, 'X-Custom-Header', 'custom-value')
  return { status: 'success' }
})

• 若该文件为冗余的测试/废弃代码，直接移除即可解决构建问题

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