Windows下Node.js无法找到json-server模块的求助排查

问题概述 #

执行node server.cjs启动Node.js服务器时，出现Error: Cannot find module 'json-server'错误，尽管json-server已在package.json中声明，且已尝试完全重装所有依赖包甚至Node.js本身。

目标 #

使用Express和json-server搭建本地后端服务器，为支持ImageKit图片上传功能的Vue.js个人页面提供服务。

错误信息 #

直接在终端运行node server.cjs时，得到如下错误：

Error: Cannot find module 'json-server'
Require stack:
- E:\Projects\catbase\server.cjs
at Module._resolveFilename (node:internal/modules/cjs/loader:1405:15)
at defaultResolveImpl (node:internal/modules/cjs/loader:1061:19)
at resolveForCJSHooks (node:internal/modules/cjs/loader:1066:22)
at Module._load (node:internal/modules/cjs/loader:1215:37)
at TracingChannel.traceSync (node:diagnostics_channel:322:14)
at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
at Module.require (node:internal/modules/cjs/loader:1491:12)
at require (node:internal/modules/helpers:135:16)
at Object.<anonymous> (E:\Projects\catbase\server.cjs:7:20)
at Module._compile (node:internal/modules/cjs/loader:1734:14) {
code: 'MODULE_NOT_FOUND',
requireStack: [ 'E:\\Projects\\catbase\\server.cjs' ]
}

相关代码 #

server.cjs #

// server.cjs

require('dotenv').config(); // Load .env file variables FIRST

const express = require('express');
const cors = require('cors');
const jsonServer = require('json-server');
const ImageKit = require('imagekit');

// --- Environment Variable Check ---
// Check if all required keys are loaded from .env
const requiredEnvVars = ['VITE_IMAGEKIT_PUBLIC_KEY', 'IMAGEKIT_PRIVATE_KEY', 'VITE_IMAGEKIT_URL_ENDPOINT'];
const missingVars = requiredEnvVars.filter(varName => !process.env[varName]);

if (missingVars.length > 0) {
    console.error('❌ FATAL ERROR: The following required environment variables are missing:');
    console.error(missingVars.join(', '));
    console.error('Please check your .env file and ensure it is in the root directory and you have restarted the server.');
    process.exit(1); // Exit the process if config is missing
}

// --- Initialize ImageKit ---
let imagekit;
try {
    imagekit = new ImageKit({
        publicKey: process.env.VITE_IMAGEKIT_PUBLIC_KEY,
        privateKey: process.env.IMAGEKIT_PRIVATE_KEY,
        urlEndpoint: process.env.VITE_IMAGEKIT_URL_ENDPOINT,
    });
} catch (error) {
    console.error('❌ FATAL ERROR: Failed to initialize ImageKit SDK. Please check your keys.');
    console.error(error);
    process.exit(1);
}

const app = express();
app.use(cors());

// --- API ROUTING ---
const apiRouter = express.Router();

apiRouter.get('/imagekit-auth', (req, res) => {
    console.log('✅ Request received for /api/imagekit-auth'); 
    try {
        const authenticationParameters = imagekit.getAuthenticationParameters();
        res.status(200).json(authenticationParameters);
    } catch (error) {
        console.error("❌ Error generating ImageKit auth params:", error);
        res.status(500).json({ message: "Could not generate auth parameters." });
    }
});

const jsonDbRouter = jsonServer.router('db.json');
apiRouter.use(jsonDbRouter); 

app.use('/api', apiRouter);

// --- START SERVER ---
const PORT = 3001;
app.listen(PORT, () => {
    console.log(`✅ Custom backend server is running on http://localhost:${PORT}`);
});

package.json #

{
  "name": "catbase",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "start": "concurrently \"npm run server\" \"npm run app\"",
    "server": "node server.cjs",
    "app": "npm run dev"
  },
  "dependencies": {
    "axios": "^1.7.2",
    "bootstrap": "^5.3.3",
    "bootstrap-icons": "^1.11.3",
    "concurrently": "^8.2.2",
    "cors": "^2.8.5",
    "dotenv": "^16.4.5",
    "express": "^4.19.2",
    "imagekit": "^5.0.1",
    "vue": "^3.4.29",
    "vue-router": "^4.3.3"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.3",
    "concurrently": "^9.1.2",
    "json-server": "^1.0.0-beta.3",
    "vite": "^6.2.4",
    "vite-plugin-vue-devtools": "^7.7.2"
  }
}

已尝试的排查步骤 #

• 确认json-server在package.json的dependencies中（而非devDependency）
• 删除node_modules和package-lock.json后执行npm install
• 执行npm cache clean --force清理npm缓存后重装
• 全局安装json-server：npm install -g json-server
• 完全卸载Windows上的Node.js，重新安装最新LTS版本
• 直接运行node server.cjs以规避npm scripts或concurrently的问题

疑问 #

既然重装Node.js和所有依赖包都无法解决问题，Windows系统下还有哪些环境因素会导致Node.js找不到本地和全局安装的模块？是否存在特定的系统权限或PATH路径问题会引发这种情况？

可能的解决方案 #

1. 检查模块安装位置与Node.js查找路径

   • 执行npm root查看本地依赖安装目录，确认json-server文件夹是否存在
   • 执行node -e "console.log(module.paths)"，查看Node.js的模块查找路径列表，确保项目的node_modules路径在其中。如果不在，检查当前终端的工作目录是否为项目根目录

2. 解决ES模块与CommonJS的冲突
   项目package.json设置了"type": "module"，但服务器文件是.cjs格式。尝试：

   • 临时移除package.json中的"type": "module"，重新执行npm install和node server.cjs
   • 手动执行npm install json-server --save，确保模块安装到dependencies中

3. Windows权限与路径检查

   • 以管理员身份运行终端，重新执行依赖安装和服务器启动命令，避免权限不足导致模块无法读取
   • 执行npm prefix -g查看全局模块路径，确认该路径已添加到系统PATH环境变量中
   • 确保项目目录路径没有特殊字符（如空格、中文），避免Node.js解析路径出错

4. 验证npm配置

   • 执行npm config get prefix确认npm全局路径是否正确，全局路径下的node_modules中是否有json-server
   • 检查系统是否存在NODE_PATH环境变量，若有则暂时移除，重启终端后测试

5. 强制重装单个模块
   执行npm uninstall json-server && npm install json-server --save，单独重装json-server模块，确保安装过程无报错

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