内容摘要：刚用HBuilder X新建了一个项目，点运行，浏览器弹出一个白底黑字的404。地址栏里写着 http://localhost:8080/项目名/，看着挺正常，但页面就是死活不出来。这事我遇到过不下十

刚用HBuilder X新建了一个项目，建项点运行，建项浏览器弹出一个白底黑字的建项404。地址栏里写着 http://localhost:8080/项目名/，建项看着挺正常，建项但页面就是建项死活不出来。这事我遇到过不下十次，建项每次都是建项不同原因。

最蠢的建项一次是项目名带了中文。HBuilder X默认把项目文件夹名直接拼进URL，建项浏览器对中文路径的建项处理千奇百怪，有的建项自动编码有的不编码，结果服务器那边收到的建项路径对不上，直接404。建项后来我养成了习惯，建项新建项目一律用英文加下划线，my_project这种，别整花活。

还有一回是端口冲突。HBuilder X内置的web服务器默认跑在8080，但我本地开了Tomcat占着这个端口。HBuilder X也不报错，默默启动失败，浏览器打开就是404。排查方法很简单，命令行敲 netstat -ano | findstr 8080，看看谁在占坑。要么关掉那个进程，要么在HBuilder X的设置里把端口改成8081之类的。

路径问题更隐蔽。新建项目时如果选了“空项目”模板，生成的结构特别干净，就一个index.html扔在根目录。但如果你后来手动建了文件夹把文件挪进去，比如移到src/下面，运行配置里的入口路径没跟着改，服务器还在根目录找index.html，找不到就404。这时候右键项目→“运行”→检查“运行配置”里的“Web服务器URL”和“启动页面”两个字段，路径要对得上文件实际位置。

有个坑我踩了两次才记住。HBuilder X新建“普通项目”时，如果模板选了“含mui”或者“含vue”，生成的文件结构不一样。vue项目会多出manifest.json和pages.json，入口文件是index.html但里面通过JS跳转。如果你直接改index.html里的内容，而没动pages.json里的路由配置，运行起来照样404——因为框架先读pages.json，发现路由指向的页面文件不存在，直接给你个空白404页。

最让人抓狂的是缓存问题。有一次改好了配置，运行还是404。清浏览器缓存、重启HBuilder X都没用。最后发现是HBuilder X内置服务器有个.hbuilderx隐藏文件夹存了旧的编译缓存，手动删掉这个文件夹再运行，好了。这破事浪费了我半小时。

说个具体案例。上周帮同事看他的项目，新建的uni-app项目，运行到浏览器404。我让他把地址栏URL发过来，一看是 http://localhost:8080/ 后面啥也没有。正常应该带项目名。检查发现他在“运行”菜单里选了“运行到浏览器”下面的“Chrome”，但没选具体的“运行”配置，HBuilder X用了个默认空路径去请求。正确操作是点工具栏那个绿色的播放按钮，或者右键项目→“运行”→选对配置。

还有种情况是文件权限。Windows下一般没事，但如果你把项目放在C盘根目录或者Program Files下面，HBuilder X的服务器进程没权限读文件，也会404。换个盘符或者用户目录下的路径就行。

排查顺序我总结了个土办法：先看URL里项目名对不对，再看端口通不通，然后检查入口文件路径，接着看模板对应的路由配置，最后删缓存。九成404跑不出这五步。要是还不行，把项目删了重建一个，有时候就是HBuilder X自己抽风，配置文件写坏了，重建比修快。

别信网上那些“改hosts”“关防火墙”的万能回复，大部分时候跟那些没关系。404就是路径对不上，找到对不上的那个点，问题就结束了。