Next.js中创建Octokit App实例时出现substr读取错误求助

问题背景 #

使用create-next-app的TypeScript模板开发GitHub App，计划通过Octokit的createNodeMiddleware实现功能，但在middleware.ts中创建App实例时触发以下错误：

TypeError: Cannot read properties of undefined (reading 'substr')
错误源自universal-user-agent依赖包。

代码片段 #

import { App } from "octokit";
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
    const myApp = new App({
        appId: 123,
        privateKey: "",        
    });

    return NextResponse.redirect(new URL('/about-2', request.url))
}

export const config = {
    matcher: '/about/:path*',
}

错误调用栈 #

Server Error
TypeError: Cannot read properties of undefined (reading 'substr')

This error happened while generating the page. Any console logs will be displayed in the terminal window.
Call Stack
<unknown>
node_modules\universal-user-agent\dist-web\index.js (6:0)
getUserAgent
node_modules\universal-user-agent\dist-web\index.js (6:26)
eval
node_modules\@octokit\endpoint\dist-web\index.js (359:64)
(middleware)/./node_modules/@octokit/endpoint/dist-web/index.js
evalmachine.<anonymous> (138:1)
__webpack_require__
evalmachine.<anonymous> (37:33)
fn
evalmachine.<anonymous> (269:21)
eval
webpack-internal:///(middleware)/./node_modules/@octokit/request/dist-web/index.js (5:75)
(middleware)/./node_modules/@octokit/request/dist-web/index.js
evalmachine.<anonymous> (248:1)
__webpack_require__
evalmachine.<anonymous> (37:33)
fn
evalmachine.<anonymous> (269:21)
eval
webpack-internal:///(middleware)/./node_modules/@octokit/core/dist-web/index.js (8:74)

排查方向与解决方案 #

原因分析 #

Next.js Middleware默认使用Edge Runtime，而universal-user-agent的web构建版本依赖浏览器环境API，在Edge Runtime中无法正常获取process等Node.js环境变量，导致内部调用substr时对象为undefined。Octokit的web构建版本不兼容Edge Runtime，需切换到Node.js环境的构建版本。

方案1：指定Middleware使用Node.js运行时 #

在middleware.ts的config中添加runtime: 'nodejs'，强制Next.js用Node.js环境运行中间件：

// middleware.ts
import { App } from "octokit";
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
    const myApp = new App({
        appId: 123,
        privateKey: "",        
    });

    return NextResponse.redirect(new URL('/about-2', request.url))
}

export const config = {
    runtime: 'nodejs', // 明确指定Node.js运行时
    matcher: '/about/:path*',
}

方案2：通过Webpack别名强制使用Octokit的Node.js构建版本 #

在next.config.js中添加Webpack配置，将Octokit相关包的web构建版本替换为node版本：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    // 替换Octokit相关包为node版本
    config.resolve.alias['@octokit/core'] = '@octokit/core/dist-node/index.js';
    config.resolve.alias['@octokit/endpoint'] = '@octokit/endpoint/dist-node/index.js';
    config.resolve.alias['@octokit/request'] = '@octokit/request/dist-node/index.js';
    config.resolve.alias['universal-user-agent'] = 'universal-user-agent/dist-node/index.js';
    return config;
  },
}

module.exports = nextConfig

额外检查 #

虽然当前错误与私钥无关，但后续GitHub App的身份验证需要有效的私钥，建议后续替换privateKey为实际的私钥内容（避免空字符串）。

内容的提问来源于stack exchange，提问作者Sean W.