用 http-server 在本机跑通静态页面：404 与端口冲突排查

这篇完成什么

在 127.0.0.1 打开自己的静态页面，核对资源请求，并能定位本次复现的两类 404 和端口冲突。

适合已安装 Node.js、会打开终端的读者。只在本机回环地址提供自己创建的测试文件，不向局域网或互联网开放。无需账号、API Key 或付费托管；下载依赖需要网络。

1. 核对环境，拿到复现资料

本次实际环境为 Node v22.22.3、npm 10.9.8、macOS 27.0.1（arm64）。Windows、Linux、其他 Node 版本和生产部署均未验证。

node --version
npm --version
mkdir npmbot-http-server-demo
cd npmbot-http-server-demo

从下方下载两个清单，放入刚建的空目录。锁文件固定了本次测试使用的依赖集合；只写顶层版本并不能固定所有间接依赖。

package.json package-lock.json

2. 按锁文件安装

npm ci --ignore-scripts --no-audit --no-fund --registry=https://registry.npmjs.org

此路线安装 http-server@14.1.1，安装阶段不运行 lifecycle scripts。后面的启动命令会实际执行这个 CLI；不要把 --ignore-scripts 当作代码沙箱。

实际两轮安装记录：added 48 packages in 3s。如锁文件与 package.json 不匹配，先核对是否完整下载了这份样章的两个文件，不要直接删除锁文件改用 latest。

3. 创建只属于本次演示的网页

mkdir -p site/assets
cat > site/index.html <<'HTML'
<!doctype html><html lang="zh-CN"><meta charset="utf-8"><title>NPMBot 本机样章</title><h1>NPMBot local preview works</h1></html>
HTML
printf 'NPMBot asset works\n' > site/assets/demo.txt

服务目录只包含这里创建的演示文件。不要把个人主目录、仓库凭据或其他私人文件当成静态站点目录。

4. 启动并完成一次访问验收

node ./node_modules/http-server/bin/http-server ./site -a 127.0.0.1 -p 8088 -c-1 -d false

保持该终端运行，在浏览器打开 http://127.0.0.1:8088/，应看到 NPMBot local preview works。在另一个终端请求：

curl -i http://127.0.0.1:8088/
curl -i http://127.0.0.1:8088/assets/demo.txt

两次均应返回 200；资源正文为 NPMBot asset works。-c-1 关闭演示中的缓存，-d false 关闭目录列表。文章使用 8088 作示例端口，自动实测选用临时空闲端口。

5. 实际复现过的排错

文件名不匹配：资源返回 404

curl -i http://127.0.0.1:8088/assets/missing.txt

本次故意请求不存在的文件，响应为 404。检查 URL 大小写、文件名和启动时的站点路径；改回 /assets/demo.txt 后实测为 200。这个例子验证排查路径，不代表所有 404 都由同一原因造成。

有 index.html，根路径仍然 404

停止服务后，在启动命令末尾增加 -i false 再运行，根路径实测返回 404，但直接请求 /index.html 仍为 200。该参数关闭了自动首页索引。移除 -i false，重新启动后根路径恢复 200；关闭目录列表只需保留 -d false。

端口占用：EADDRINUSE

保持第一个服务运行，再用同一命令启动第二个服务。本次第二个进程非零退出，并出现下面从实际日志提取、仅替换端口的行：

Error: listen EADDRINUSE: address already in use 127.0.0.1:<test-port>

先用 Ctrl+C 停止自己刚启动的服务，或把端口改为另一个空闲值，并同步修改访问 URL。不要为了教程结束不认识的进程。

6. 重启、停止与清理

用 Ctrl+C 停止服务，按步骤 4 再启动。两轮实测均在重启后取回相同 HTML；资源请求已在前面的验收中检查。停止后，原回环地址不可连接。此示例没有数据库或云资源。

确认服务已停止后，可通过文件管理器删除自己创建的 npmbot-http-server-demo 目录。没有全局安装包，不需要卸载全局工具，也没有需要取消的托管订单。

7. 真实运行记录与边界

同一操作者在两个新临时目录、两个新 npm 缓存中各运行一次，安装、首页 200、资源 404→200、端口冲突、自动首页关闭、重启和停止均通过。没有使用 VM 或容器沙箱；没有独立读者盲测，也没有抓取浏览器截图。

两个本机运行记录
运行	安装	首页	缺失资源 / 修正	冲突	重启
local-1	退出码 0	200	404 / 200	EADDRINUSE	200
local-2	退出码 0	200	404 / 200	EADDRINUSE	200

上述结果只对应本文精确环境与本地文件，不构成安全审计、跨平台保证或生产部署结论。上游新版本、云平台和外网访问需要另行验证。

版本、摘要与原始记录

npm 发布包 SRI: sha512-+cbxadF40UXd9T01zUHgA+rlo2Bg1Srer4+B4NwIHdaGxAGGv59nYRnGGDJ9LBk7alpS0US+J+bLLdQOOkJq4A==
测试锁文件 SHA-256: c88c7448279f679182855da97d959ebba5447a12781fffd4c50a6007e2cbac3b
npm 元数据中的 gitHead: af0ac3e4b9bd5fff55337aee32bf37f6116c7b4f
验证时间: 2026-11-03T08:58:52.142Z

下载 verification.json

来源、授权与当前交付状态

本文是原创操作记录，软件由上游维护，http-server 14.1.1 声明为 MIT。保留上游来源，样章不把工具包装成自研软件或官方认证。

当前完整样章和复现资料均免费。没有付款入口、付费承诺或远程代部署服务；若后续推出付费手册，会先写明范围、价格、更新与支持期限。