从开发到部署：关于 EdgeOne Pages 的 Next.js 全栈最佳实践

本指南致力于帮助您构建高性能的 Next.js 全栈应用，在优化开发工作流程的同时，确保代码质量和应用性能始终保持最佳状态。

后续章节将深入探讨项目架构、环境配置、路由策略以及高效的数据获取技术。这些最佳实践将助您在 EdgeOne Pages 平台上顺畅部署 Next.js 全栈应用，充分发挥边缘计算优势，实现卓越性能与全球化访问体验。

目录结构建议

以下目录结构是我们推荐的 Next.js 混合渲染模板。这个项目架构为构建可扩全栈应用程序提供了基础：

next-mix-template/
├── src/                   
│   ├── app/               # Next.js 应用路由
│   │   ├── layout.tsx     
│   │   ├── page.tsx        # 首页组件
│   │   ├── ssr/            # SSR 演示页面
│   │   ├── isr/            # ISR 演示页面
│   │   ├── ssg/            # SSG 演示页面
│   │   ├── streaming/      # 流媒体演示页面
│   │   ├── node-functions/ # Node Functions 演示页面
│   │   ├── edge-functions/ # Edge Functions 演示页面
│   │   ├── api/            # API 路由
│   │ └── globals.css    
│   ├──/        # React 组件
│   │  ── ui/           
│   │   ├── Header.tsx    
│   │   ├ Hero.tsx      
│   │   ├── Features.tsx  
│   │   └ FeatureCard.tsx 
│   └── lib/ # 工具函数
├── public/               # 静态资源
├── package.json          # 项目配置
├── next.config.ts        # Next.js 配置
├── tailwind.config.ts    
├── tsconfig.json         
└── components.json       # shadcn/ui 配置

该项目遵循标准的 Next.js App Router 架构，具有两个专门的后端函数目录，能够与 EdgeOne Pages 无缝集成：

edge-functions 目录作为 EdgeOne Pages 边缘计算能力的入口。将轻量级请求置于此处，以便从离用户最近的边缘节点执行，获得快速的响应时间，提供卓越的速度和性能。

node-functions 是一个基于 Node.js 的函数部署环境，您可以利用庞大丰富的 Node.js 生态完成开发。

有关 edge-functions 和 node-functions 的更全面的细节，请参阅官方文档。

路由和 API 集成

EdgeOne Pages 通过域名的路径提供页面和 API 端点的直接访问。映射遵循一致的模式，其中文件位置与 URL 路径直接对应——例如，/app/node-functions/get-users/index.js 可在 {domain}/get-users 访问。

该平台具有直观的路由系统，关键特性：

• 自动路径映射：文件系统结构直接翻译为 URL 路由
• 零配置：无需手动路由设置
• 统一路由管理：无缝处理页面和 API 路由

项目结构:
/app/node-functions/get-users/index.js
/app/node-functions/create-user/index
/app/node-functions/products/[id].js

/app/edge-functions/get-products/index.js (edge)

访问:
https://yourdomain/get-users      → 运行 get-users/index.js
https://yourdomain.com/create-user    → 运行 create-user/index.js
https://yourdomain/products/products//123123     →  运行运行 products products/[/[idid].].js
https://yourdomain.com/get-products   → 运行 get-products/index.js (edge)

页面渲染数据获取

Next.js 提供多种渲染策略，每种都有不同的数据获取机制。EdgeOne Pages 全面支持 Next.js 的三种主要渲染模式——静态站点生成（SSG）、服务器端渲染（SSR）和增量静态再生（ISR），开发者能够在同一应用程序中灵活混合使用这些策略。

1. 应用路由数据获取（Next.js 13+）

Next.js 新的应用路采用不同的数据获取方法。有关全面的细节，请查阅官方 Next.js 文档。

// app/products/page.js
// 默认静态渲染
async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    cache: 'force-cache' // 默认缓存
  })
  res.json()
}

export default async function ProductsPage() {
  const products = await getProducts()
  
  return (
    <div>
      {products.map(product => (
        <div key={product.id}>product.name}</div>
      ))}
    </div>
  )
}

将 revalidate: 0 设置为强制页面在每个请求上使用服务器端渲染进行数据检索。

// app/live/page.js
// 动态渲染（类似于 getServerSideProps）
async function getLiveData() {
  const res = await fetch('https://api.example.com/live', {
    cache: 'no-store', // 不缓存，每次请求获取新数据
    // 或使用
    next: { revalidate: 0 }
  })
  return res.json()
}

// 在应用路由中的 ISR
async function getDataWithISR() {
  const res = await fetch('https://api.example.com/data', {
    next: { revalidate: 60 } // 60 秒后重新验证
  })
  return res.json()
}

// pages/dashboard.js
// 结合静态和客户端数据获取
export async function getStaticProps() {
  // 获取不经常变化的数据
  const staticData = await fetch('https://api.example.com/config')
  const config = await staticData.json()

  return {
    props: { config },
    revalidate: 3600, // 1 小时
  }
}

function Dashboard({ config }) {
  // 客户端获取实时数据
  const { data: liveData } = useSWR('/api/live-stats', fetcher, {
    refreshInterval: 5000
  })

  return (
    <div>
      <h1>{config.title}</h1>
      {liveData && <;在线用户: {liveData.onlineUsers}</div>}
    </div>
  )
}

2. getStaticProps（静态生成）

在构建过程中获取数据并生成静态 HTML 页面。适合不需要频繁更新相对稳定的内容。

// pages/products.js
export async function getStaticProps() {
  const res = await fetch('https://api.example.com/products')
  const products = await res.json()

 return {
    props: {
      products,
    }
  }
}

export default function Products({ products }) {
  return (
    <div>
      {products.map(product => (
        <div key={product.id}>{product.name}</div>
      ))}
    </div>
  )
}

用例： Next.js 官方网站（nextjs.org）

3. getServerSideProps（服务端渲染）

服务端渲染（SSR）在每次页面请求时从服务器检索数据。这种方法非常适合实时数据更新或访问特定信息的页面。

// pages/user/[id].js
export async function getServerSideProps(context {
  const { id } = context.params
  const {, res, query } = context
  
  const cookies = context.req.cookies
  
  const user = fetch(`https://api.example.com/users/${id}`)
  const user = await userData.json()

  if (!user) {
    return {
      notFound: true, 
    }
  }

  return {
    props: {
      user,
    }
  }
}

export default function User({ user }) {
  return <div>欢迎, {user.name}!</div>
}

用例： LinkedIn（linkedin.com）

4. ISR（增量静态再）

revalidate 参数启用增量静态再生（ISR），提供规则基础的按需页面数据更新。

export async function getStaticProps() {
  const res = await fetch('https://api.example.com/blog')
  const posts = await res.json()

  return {
    props: {
      posts,
    },
    // 三种 ISR 策略
    revalidate: 60, // 在秒数间隔后重新生成    // 或者
    revalidate: false, // 禁用 ISR，仅在构建时生成
    // 或者
    re: true, // 按需 ISR（需要配置）
  }
}

用例： Dev.to（dev.to）热门内容每 5 分钟更新一次

方法比较与决策矩阵

开发人员使用决策矩阵：

环境变量管理

EdgeOne Pages 遵循 Next.js 关于环境变量管理的约定：

• 公共变量：以 `NEXT_PUBLIC_` 开头的环境变量将嵌入到客户端包中，并在浏览器代码中可访问。这些变量不应包含敏感信息。
• 受保护变量：对于敏感信息，如 API 密、认证令牌（如 `AI_TOKEN`）或其他凭据，避免 `NEXT_PUBLIC_` 前缀。这些变量将仅保留在服务器端，保护它们不被暴露于客户端代码中。

这种一致的方法使您能够管理变量的可见性和安全性，同时与标准 Next.js 环境变量系统的兼容性。

# 私有环境

OPENAI_API_URL=
OPENAI_API=

DB_HOST=
DB_PORT=
DB_USER=
DB_PASSWORD=
DB_NAME=

# 公共环境

NEXT_PUBLIC_AUTHOR=
NEXT_PUBLIC_EMAIL=

通常情况下，使用 .env.local 文件即可满足需求。但在某些场景下，您可能需要为开发环境（next dev）或生产环境（next start）分别设置特定的默认配置。

Next.js 支持在 .env（所有环境）、.env.development（开发环境）和 .env.production（生产环境）中设置默认值，而 .env.local 的配置始终具有最高优先级。

部署到 EdgeOne Pages 时，需要在 EdgeOne 控制台中配置与本地 .env 文件相对应的环境变量。EdgeOne Pages 遵循 Next.js 的标准约定：以 NEXT_PUBLIC_ 为前缀的变量会嵌入到客户端代码中，而无此前缀的变量则安全地保留在服务器端。

注意为了安全起见，请始终将 .env* 文件添加到您的 .gitignore 中，以防止敏感凭据如 API 密钥和令牌被意外提交到您的存储库。

总结

EdgeOne Pages 为 Next.js 全栈项目提供全面的原生支持，完美兼容静态站点生成（SSG）、服务器端渲染（SSR）、增量静态再生（ISR）和 API 路由等核心特性。开发者无需复杂配置即可充分发挥 Next.js 框架的所有优势，灵活选择渲染策略，享受高效的全栈开发体验。

借助 EdgeOne Pages 的简化部署流程，开发团队可通过 EdgeOne CLI 或其他方式快速将 Next.js 应用部署到全球边缘网络。这种无缝部署不仅大幅降低了运维复杂度，还通过边缘计算能力提供卓越的性能和可靠性，让开发者能够专注于业务逻辑实现，无需担心基础设施管理与优化。