如何通过FTP部署支持动态API请求的Nuxt 3应用

一、静态生成后 API 请求异常的排查与修复 #

1. 检查 API 基础地址配置 #

确保你在 nuxt.config.ts 或环境变量中配置的 API 地址是服务器公网可访问的，而非开发环境的 localhost 或 127.0.0.1：

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: 'https://你的服务器域名/api' // 替换为实际公网 API 地址
    }
  },
  ssr: false
})

在页面中调用 API 时，使用配置的公网地址：

const { data } = await useFetch(`${useRuntimeConfig().public.apiBase}/users`)

2. 排查跨域（CORS）问题 #

如果 Laravel API 和 Nuxt 静态站点不在同一域名下，需要在 Laravel 中配置 CORS 允许静态站点的域名访问：
在 Laravel 的 config/cors.php 中修改 paths 和 allowed_origins：

return [
    'paths' => ['api/*'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['https://你的Nuxt站点域名'], // 或用 '*' 临时测试（生产环境不建议）
    'allowed_origins_patterns' => [],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => false,
];

修改后记得重启 Laravel 服务。

3. 确认静态页面的请求时机 #

当 ssr: false 时，所有 API 请求都是在浏览器端发起的，确保你的页面逻辑是在客户端执行的（避免在 serverInit 等服务端生命周期钩子中发起请求）。

二、npm run build 报错的处理 #

首先必须获取完整的错误信息，执行以下命令并复制全部输出：

npm run build --verbose

常见报错原因及解决方法：

• 依赖缺失：删除 node_modules 和 package-lock.json，重新执行 npm install
• 环境变量未定义：检查 .env 文件是否包含 Nuxt 所需的环境变量（比如 NUXT_PUBLIC_API_BASE），确保部署服务器上的环境变量配置正确
• 配置语法错误：检查 nuxt.config.ts 是否有语法错误，比如未闭合的括号、类型错误等
• 端口占用：如果 build 过程中提示端口被占用，可以指定其他端口：npm run build -- --port 3001

三、实现「部分页面静态、部分页面可请求 API」的需求 #

你可以结合 Nuxt 3 的静态生成和客户端渲染特性实现：

1. 保持 ssr: false，确保所有页面为客户端渲染模式
2. 对需要纯静态的页面，在 nuxt.config.ts 中配置 generate.routes 指定预渲染路由：

export default defineNuxtConfig({
  ssr: false,
  generate: {
    routes: ['/', '/about', '/contact'] // 这些路由会被预渲染为静态 HTML
  }
})

3. 执行 npx nuxi generate 生成静态文件，dist 目录下的文件即可通过 FTP 部署到服务器
4. 对于需要动态请求 API 的页面，无需额外配置，只要 API 请求逻辑正确，页面在浏览器加载时会自动发起请求获取数据

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