Next.js项目npm run dev编译成功但浏览器报404错误求助

环境与现象 #

• 系统：Windows 11
• 技术栈：Next.js + React + TypeScript
• 现象：执行npm run dev后终端显示编译成功，但访问http://localhost:3000返回404，npm run start也出现相同问题

终端输出 #

PS C:\Users\hosap\Documents\Programming\NextJSApplication\next-typescript> npm run dev

> next-typescript@0.1.0 dev
> next dev

ready - started server on 0.0.0.0:3000, url: http://localhost:3000
info  - Loaded env from C:\Users\hosap\Documents\Programming\NextJSApplication\next-typescript\.env
event - compiled client and server successfully in 1315 ms (150 modules)
wait  - compiling /_error (client and server)...
event - compiled client and server successfully in 219 ms (151 modules)
warn  - Fast Refresh had to perform a full reload. Read more: https://nextjs.org/docs/messages/fast-refresh-reload

项目结构 #

.next/ (npm run dev时自动生成) 
.swc/
.vscode/
   settings.json
.VSCodeCounter/
node_modules/
public/
   images/
   logo/
   favicon.ico
src/
   components/
   elements/
   functions/
   lib/
   pages/
   styles/
.env
.eslintrc.json
.gitignore
environment.d.ts
jest.config.js
next-env.d.ts
next.config.js
package-lock.json
package.json
README.md
setupTests.js
tsconfig.json

pages目录结构 #

pages/
   api/
      search.ts
   search/
   _app.tsx
   _document.tsx
   404.tsx
   about-us.tsx
   index.tsx

关键配置文件 #

next.config.js #

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  pageExtensions: ['page.tsx', 'page.ts', 'page.jsx', 'page.js']
}

module.exports = nextConfig

package.json #

{
  "name": "next-typescript",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "lint": "next lint"
  },
  "dependencies": {
    "@next/font": "13.1.1",
    "@types/node": "^18.11.17",
    "@types/react": "18.0.26",
    "@types/react-dom": "18.0.10",
    "classnames": "^2.3.2",
    "eslint-config-next": "13.1.1",
    "jest-environment-jsdom": "^29.5.0",
    "next": "13.1.1",
    "react": "18.2.0",
    "react-dom": "18.2.0"
  },
  "devDependencies": {
    "@babel/preset-typescript": "^7.21.0",
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^14.0.0",
    "@types/enzyme": "^3.10.12",
    "@types/jest": "^29.5.0",
    "@typescript-eslint/eslint-plugin": "^5.48.0",
    "eslint": "^8.31.0",
    "eslint-config-standard-with-typescript": "^26.0.0",
    "eslint-plugin-import": "^2.26.0",
    "eslint-plugin-n": "^15.6.0",
    "eslint-plugin-promise": "^6.1.1",
    "eslint-plugin-react": "^7.31.11",
    "jest": "^29.5.0",
    "next-router-mock": "^0.9.7",
    "typescript": "^4.9.4"
  }
}

environment.d.ts #

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: 'development' | 'production'
      API_KEY: string
      URL: string
    }
  }
}

export {}

已尝试的解决方法 #

• 执行npm ci重新安装依赖
• 重启电脑
• 移除environment.d.ts中的空导出

问题原因与解决方案 #

问题核心是next.config.js里的pageExtensions配置：你指定页面文件必须以.page.tsx/.page.ts等后缀结尾，但当前pages目录下的文件（比如index.tsx、about-us.tsx）都没有添加.page后缀，导致Next.js无法识别这些文件为页面组件，因此返回404。

两种解决方式任选其一：

1. 修改文件名：给所有页面文件加上.page后缀，比如index.tsx改为index.page.tsx，about-us.tsx改为about-us.page.tsx；_app.tsx、_document.tsx这类特殊文件也建议同步调整。
2. 修改配置：在next.config.js的pageExtensions中添加现有文件的后缀，兼容两种命名规则：

const nextConfig = {
  reactStrictMode: true,
  pageExtensions: ['tsx', 'ts', 'jsx', 'js', 'page.tsx', 'page.ts', 'page.jsx', 'page.js']
}

修改后重启开发服务器，即可正常访问页面。

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