Next.js自定义服务器添加/product-ui前缀时路由映射报错排查

问题现象 #

为Next.js自定义服务器添加/product-ui前缀后，出现路由兼容错误：提供的as值(/product-ui/order/EC0701HICR)与href值(/order/[orderId])不兼容。尝试配置URL转换未解决，附上自定义服务器代码请求排查。

错误详情 #

错误提示：提供的as路径/product-ui/order/EC0701HICR与href路径/order/[orderId]不匹配，Next.js无法正确解析路由映射。

自定义服务器代码 #

const express = require('express');
require('dotenv').config();
const next = require('next');
const { parse } = require('url')

const orderRoute = require('./routes/order.route');
const promotionRoute = require('./routes/promotion.route');
const port = parseInt(process.env.PORT, 10) || 3000;
const dev = process.env.NODE_ENV !== 'production';
const nextApp = next({ dev })
const handle = nextApp.getRequestHandler()

const VERSION_API = 'v1';

const server = express();
nextApp.prepare().then(() => {
  server.use(express.json());

  server.use(`/${VERSION_API}/api/order`, orderRoute);
  server.use(`/${VERSION_API}/api/promotion`, promotionRoute);

  server.get('/order/:orderId', (req, res) => {
    const { orderId } = req.params;
    const actualPage = `/order/${orderId}`;
    const queryParams = req.query;
    return nextApp.render(req, res, actualPage, queryParams);
  })

  server.get('*', (req, res) => {
    return handle(req, res)
  })

  express().use("/product-ui", server).listen(port, err => {
    if (err) throw err
    console.log(`> Ready on http://localhost:${port}`)
  })
})

问题原因及解决方法 #

核心问题 #

整个Next应用挂载到/product-ui前缀下，但Next的路由解析（包括next/link或router.push生成的URL）默认基于根路径，未带上/product-ui前缀，同时自定义路由处理也未考虑前缀影响，导致as和href路径不匹配。

具体修复步骤 #

1. 配置Next.js基础路径
   在项目根目录的next.config.js中添加basePath，让Next自动给所有路由加上前缀：

module.exports = {
  basePath: '/product-ui',
}

2. 修正自定义路由的路径匹配
   调整/order/:orderId路由，匹配带前缀的路径，同时明确区分Next内部页面路径和浏览器显示路径：

// 替换原有的order路由
server.get('/product-ui/order/:orderId', (req, res) => {
  const { orderId } = req.params;
  // actualPage是Next项目内部的页面路径，不带前缀
  const actualPage = '/order/[orderId]';
  // 传递参数给页面
  const queryParams = { orderId, ...req.query };
  // as参数传入浏览器实际显示的完整路径
  return nextApp.render(req, res, actualPage, queryParams);
})

3. 优化服务器挂载方式
   将前缀整合到主服务器配置，避免嵌套express实例的混淆：

// 替换原有的服务器启动代码
server.listen(port, err => {
  if (err) throw err
  console.log(`> Ready on http://localhost:${port}/product-ui`)
})

// 给所有API路由加上/product-ui前缀
server.use(`/product-ui/${VERSION_API}/api/order`, orderRoute);
server.use(`/product-ui/${VERSION_API}/api/promotion`, promotionRoute);

额外注意事项 #

• 使用next/link时，无需手动添加/product-ui前缀，Next会自动基于basePath生成正确URL
• 使用router.push时，直接写内部路径（如/order/EC0701HICR）即可，Next会自动拼接前缀

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