企业级Nginx静态服务需统一路径语义、隔离资源类型、适配部署环境：/css/仅存CSS、/js/仅存构建JS、/images/分用途子目录、/fonts/独立存放字体、/media/限速防盗链；dev/staging/prod通过URL前缀区分，资源用哈希命名；root仅用于主站入口，子路径必须alias绝对路径；预留/health/、/static-meta.json、/.well-known/等安全可观测路径。
企业级 Nginx 静态服务要稳定、可维护、易交接，目录命名不能靠经验或临时发挥。核心是统一路径语义、隔离资源类型、适配部署上下文，同时规避权限、缓存、安全层面的隐性冲突。
统一资源类型前缀与大小写规范
所有静态资源 URL 路径必须以小写英文前缀开头，禁止拼音、数字起始、下划线或混合大小写。这是为兼容 CDN 缓存策略、避免大小写敏感系统（如 Linux）误判 404，也便于日志分析和前端引用标准化。
- /css/：仅存放 .css 文件，不混入 .scss/.less 源文件
- /js/：仅存放已构建的 .js 文件（含模块化产物如 chunk-xxx.js），源码和 map 文件走构建流程管理
- /images/：存放所有图片资源（.png/.jpg/.webp/.svg），子目录可按用途分：/images/icons/、/images/banners/、/images/avatars/
- /fonts/：字体文件（.woff2/.woff/.ttf），禁止放在 /css/ 或 /js/ 下
- /media/：音视频等大体积资源（.mp4/.webm/.mp3），建议配合独立限速与 referer 防盗链
环境与版本分离路径设计
同一套前端代码在 dev/staging/prod 环境中，不应靠修改 Nginx 配置切换资源路径，而应通过 URL 前缀显式标识。这样可避免配置漂移，也支持灰度发布和 AB 测试。
- 开发环境用 /dev/ 前缀（如
/dev/js/app.js），Nginx 可映射到本地构建输出目录 - 预发环境用 /staging/，资源路径与生产一致但指向独立静态桶或子目录
- 生产环境根路径直接暴露（
/js/app.js），或统一加 /prod/ 前缀便于 CDN 多环境缓存隔离 - 带版本号的资源建议用哈希命名（
app.a1b2c3d4.js），不依赖路径版本（如/v2.3/js/），避免重复部署时缓存失效问题
禁止裸 root 共享与 alias 使用红线
多个静态目录共用同一个物理 root 是常见隐患——权限冲突、缓存头错配、路径覆盖都可能引发线上故障。必须明确区分 root 与 alias 的使用场景。
- 全局
root仅用于主站入口（如location / { root /data/www; }），且该目录下只放 index.html 和基础跳转页 - 所有子路径（如
/api-docs/、/downloads/）必须用alias映射到独立物理路径，且末尾斜杠不可省略：alias /data/static/downloads/; - 禁止在不同 location 中对同一物理路径使用不同 root —— 例如
/css/和/js/都指向/data/build/，但分别配了不同 expires，这会导致缓存头实际生效逻辑混乱 - 所有 alias 路径必须为绝对路径，Docker 环境中需确保挂载路径与配置中完全一致
安全与可观测性配套路径约定
命名不只是“能访问”，还要支撑审计、监控和应急响应。预留专用路径，让安全策略和运维动作有据可依。
-
/health/：返回纯文本
OK，供负载均衡器健康检查，不走任何缓存 - /static-meta.json：由构建流程自动生成，包含资源哈希、构建时间、Git commit，供前端诊断版本
- /.well-known/：标准 ACME、robots.txt、security.txt 等合规文件存放点，禁止用于业务资源
- 禁止开放
autoindex on的任意目录（如/uploads/），确需目录列表的，必须限定在专用路径如/public-listings/，并启用autoindex_exact_size off;防止泄露精确文件大小
