选 alias：当 url 路径与磁盘目录名称不一致时，alias 可替换前缀，如 /api/docs/ → /opt/swagger-ui/；选 root：当结构一致时更简洁，如 /static/ → /var/www/static/。

选 root 还是 alias，关键看 URL 路径和磁盘目录是否“名字对得上”。对不上就用 alias，对得上且结构一致，root 更简洁直接。

root：拼完整路径，要求磁盘有对应子目录

root 的逻辑是：最终路径 = root 值 + 完整请求 URI。它不删减、不替换，原样拼接。

• location /static/ { root /var/www; } → 请求 /static/css/app.css，实际找的是 /var/www/static/css/app.css
• 这意味着 /var/www 下必须真实存在 static/ 子目录，否则 404
• 适合整站部署：比如 Vue 打包产物放在 /var/www/dist，用 location / { root /var/www/dist; }，访问 / 就对应 dist/index.html
• root 值末尾加不加 / 都行，Nginx 会自动处理，但统一写成 /var/www/dist/ 更清晰

alias：换前缀，不依赖磁盘层级

alias 的逻辑是：把 location 匹配到的部分整个去掉，再把剩余 URI 拼到 alias 值后面。

Browser Setup (No-Root Linux)

在无 root/sudo 权限的环境（云容器、VPS、隔离主机）中安装并配置 OpenClaw 浏览器工具的 headless Chrome。适用场景：...

下载

• location /api/docs/ { alias /opt/swagger-ui/; } → 请求 /api/docs/index.html，实际找的是 /opt/swagger-ui/index.html
• 注意：alias 值末尾必须带 /，漏掉就会变成 /opt/swagger-uiindex.html（少斜杠，路径错）
• location 也建议以 / 结尾（如 /api/docs/），避免正则或截断歧义
• 适合挂载外部资源：CDN 路径映射、子应用部署（/admin/ → /srv/my-admin/）、共享图标库（/assets/icons/ → /mnt/icons/）

不能混用，且 location 写法影响结果

同一 location 块里，root 和 alias 互斥，Nginx 启动直接报错。

• location /web { root /var/www/project/dist; } → 实际查 /var/www/project/dist/web/index.html（多了一层 web）
• 改成 location /web/ { alias /var/www/project/dist/; } → 请求 /web/ 就对应 dist/ 下的文件，干净利落
• 如果 location 写成 /web（无结尾 /），而 alias 是 /dist/，那么 /webfile.js 会被拼成 /distfile.js —— 错误就在这一道斜杠里

调试和验证的小技巧

改完配置别急着 reload，先确认两件事：

• 用 nginx -t 检查语法，避免低级错误
• 查 error.log，重点看 “open() failed” 后面的真实路径，它告诉你 Nginx 究竟想找哪个文件
• 临时加一条 try_files $uri =404;，配合 curl -I 测试，快速验证路径是否可达
• 浏览器访问时加 ?v=1 强制绕过缓存，避免被旧响应误导