ASP.NET Core本地正常 服务器端JS/CSS/图片静态资源404排查

已确认的问题特征 #

• 本地开发环境运行时，所有JS、CSS、图片资源加载完全正常，无报错
• 已核对Razor布局页中的静态资源路径配置，未发现拼写错误
• 未自定义修改默认Web根目录（wwwroot）配置，后端Kestrel服务监听5000端口
• 部署环境为树莓派运行Ubuntu，前置接入Apache反向代理
• 直接在浏览器访问静态资源完整URL时，本地可正常获取内容，服务器端返回404

分步排查与解决方案 #

1. 优先排查Apache反向代理配置 #

这是这类跨环境静态资源404的最高发原因：

• 先确认Apache必需模块已启用：
  执行命令sudo a2enmod proxy proxy_http headers开启反向代理、请求头透传相关模块，执行后重启Apache服务生效
• 核对站点反代规则配置：
  确保没有错误配置本地静态资源映射，避免Apache拦截静态资源请求后在错误的本地目录中查找文件。正确的根路径部署反代配置如下：

  <VirtualHost *:80>
      ServerName your-domain.com
      ProxyPreserveHost On
      # 所有请求透传给本地Kestrel服务
      ProxyPass / http://127.0.0.1:5000/
      ProxyPassReverse / http://127.0.0.1:5000/
      # 透传原始请求头，避免路径识别错误
      RequestHeader set X-Forwarded-Proto "http"
      RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}s"
  </VirtualHost>
  

  注意：如果应用部署在非根路径下（如http://domain.com/app/），除了调整反代的路径映射，还需要在ASP.NET Core程序中配置对应PathBase，否则生成的静态资源URL会缺失路径前缀，导致404。

2. 检查Linux文件权限与发布文件完整性 #

Ubuntu系统的权限规则和Windows不同，容易出现两类问题：

• 权限不足：ASP.NET Core进程的运行用户（通常为www-data）没有权限读取wwwroot下的静态文件。可通过以下命令修正权限：

  # 将项目目录的所有者改为运行进程的系统用户
  sudo chown -R www-data:www-data /你的项目部署路径
  # 为wwwroot目录开启全局读取权限
  sudo chmod -R 755 /你的项目部署路径/wwwroot
  

• 发布文件缺失：执行dotnet publish时，如果发布配置中排除了静态资源文件，会导致服务器端wwwroot目录是空的或缺少对应文件。直接登录服务器查看项目下的wwwroot目录结构，和本地发布的输出目录逐一核对，确认所有静态资源文件已同步到位。

3. 核对ASP.NET Core请求管道配置 #

虽然本地环境正常通常意味着此配置无误，但仍需确认：

• 在Startup.cs的Configure方法中，app.UseStaticFiles()必须放在app.UseRouting()、app.UseEndpoints()之前调用，否则静态资源中间件不会拦截对应的资源请求，会直接走路由逻辑返回404。

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