Nuxt 3 使用 node-server 预设构建时，仅需部署 .output 目录（已内嵌精简版 node_modules），.nuxt 目录纯属构建中间产物，无需上传；本文详解部署流程、常见误区及模块依赖补充策略。
nuxt 3 使用 node-server 预设构建时，仅需部署 `.output` 目录（已内嵌精简版 node_modules），`.nuxt` 目录纯属构建中间产物，无需上传；本文详解部署流程、常见误区及模块依赖补充策略。
在 Nuxt 3 中启用 node-server 预设（即通过 nuxi build --preset node-server 或配置 nitro.preset = 'node-server'）后，构建输出被严格分离为两个目录：
-
.nuxt/：仅用于开发与构建阶段，包含类型声明、Vite/Nitro 中间缓存、编译产物临时文件等，不参与运行时，也不包含任何 node_modules —— 这是设计使然，而非遗漏。 -
.output/：唯一需要部署的生产目录，由 Nitro 构建器生成，已将运行时必需的依赖（如vue,@vue/server-renderer,unenv,nitropack及所用 Nuxt 模块的 runtime 代码）以“扁平化 + tree-shaken”方式打包进其内置的node_modules中。该目录可直接通过node .output/server/index.mjs启动服务。
✅ 正确部署步骤如下：
# 1. 构建（确保 preset 明确指定） npx nuxi build --preset node-server # 2. 部署（仅复制 .output，无需 .nuxt，无需根目录 node_modules） scp -r .output user@your-server:/var/www/my-nuxt-app/ # 3. 启动（在服务器上执行） cd /var/www/my-nuxt-app NODE_ENV=production node .output/server/index.mjs
⚠️ 注意事项：
-
切勿上传
.nuxt或本地node_modules：这不仅冗余，还可能引发版本冲突或安全风险（如 devDependencies 被意外加载）。 -
静态资源路径需对齐：若项目含
public/下的文件（如favicon.ico,robots.txt），它们会自动复制到.output/public/，无需额外操作。 -
模块特有资源需手动同步：例如使用
@nuxt/content时，content/目录（含.md文件）不会自动打包进.output，须一并上传至服务器对应位置（通常与.output同级）：# 示例：同步 content 目录 scp -r content/ user@your-server:/var/www/my-nuxt-app/content/
其他类似模块（如
@nuxt/image的images/目录、自定义server/API 路由外挂文件）均需按文档确认是否需额外部署。
? 验证部署完整性：
启动服务后，访问 http://localhost:3000/_nitro（开发时）或检查日志中 Listening on http://[::]:3000 即可确认 SSR 服务正常；同时可通过 curl -I http://localhost:3000 查看响应头是否含 x-powered-by: Nitro 和正确 content-type。
总结：Nuxt 3 的 node-server 预设践行了“零依赖部署”理念——.output 是自包含的生产包。理解 .nuxt（构建期）与 .output（运行期）的职责边界，是避免重复上传、提升部署可靠性与安全性的关键。
