Nginx环境（Ubuntu 24.04）下如何在Leaflet中引用自建OpenStreetMap瓦片

阿华AIGC实验室

2026-3-30

嗨，我之前也碰到过一模一样的问题——跟着教程搭完Mapnik、PostgreSQL这些核心组件，结果服务器用的是Nginx，找不到对应mod_tile的配置方法，折腾了好一阵才搞定。下面是我在Ubuntu 24.04上亲测有效的步骤，全是干货：

一、先确认renderd服务的配置（它是瓦片渲染的核心）

不管用Apache还是Nginx，renderd都是负责动态渲染瓦片的核心服务，之前的Switch2OSM教程里应该已经帮你装好了。我们只需要确保它的配置能和Nginx对接：

编辑renderd的主配置文件：
```
sudo nano /etc/renderd.conf
```
找到[renderd]段，重点看两个关键配置：
- socketname=/run/renderd/renderd.sock：这是默认的Unix套接字，Nginx可以通过它和renderd通信；如果你觉得套接字权限麻烦，也可以改成HTTP端口监听，比如加一行port=7654（记得注释掉原socketname配置）
- tile_dir=/var/lib/mod_tile：这是瓦片缓存的存储目录，一定要记下来，后面Nginx配置要用到
保存退出后，重启renderd并检查运行状态：
```
sudo systemctl restart renderd
sudo systemctl status renderd
```
看到active (running)的绿色提示就没问题了。

二、配置Nginx反向代理+静态缓存

Nginx不需要安装特殊模块，只要通过反向代理对接renderd，同时优先返回已缓存的静态瓦片（能大幅提升访问速度）：

创建一个新的Nginx站点配置文件：

sudo nano /etc/nginx/sites-available/osm-tiles

粘贴下面的配置（把your-server-ip-or-domain换成你的服务器IP或自定义域名）：

server {
    listen 80;
    server_name your-server-ip-or-domain;

    # 优先返回已缓存的静态瓦片
    location /tiles {
        root /var/lib/mod_tile;
        # 解析瓦片路径：/tiles/z/x/y.png 对应缓存目录里的 z/x/y/zxy.png
        rewrite ^/tiles/(\d+)/(\d+)/(\d+)\.png$ /$1/$2/$3/$1$2$3.png break;
        try_files $uri @renderd;
    }

    # 未缓存的请求转发给renderd动态渲染
    location @renderd {
        # 如果用Unix套接字，保留这个配置
        fastcgi_pass unix:/run/renderd/renderd.sock;
        fastcgi_param SCRIPT_NAME "";
        fastcgi_param PATH_INFO $fastcgi_script_name;
        include fastcgi_params;

        # 如果之前改了用HTTP端口，就替换成下面这行：
        # proxy_pass http://127.0.0.1:7654;
    }

    # 允许跨域（如果你的Leaflet页面和瓦片服务器不在同一域名下，必须加这个）
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, HEAD, OPTIONS";
    add_header Access-Control-Allow-Headers "X-Requested-With";
}

保存退出后，先检查Nginx配置有没有语法错误：
```
sudo nginx -t
```

启用这个站点并重启Nginx：

sudo ln -s /etc/nginx/sites-available/osm-tiles /etc/nginx/sites-enabled/
sudo systemctl restart nginx

最后处理权限坑（我当时卡了好久）：
让Nginx用户能访问renderd的套接字和瓦片缓存目录：
```
sudo chown -R renderd:www-data /run/renderd
sudo chown -R www-data:www-data /var/lib/mod_tile
```

三、Leaflet中加载自建瓦片

这一步就简单了，只要在你的Leaflet代码里，把瓦片源指向Nginx配置的路径就行：

<!-- 先引入Leaflet的CSS和JS -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

<div id="map" style="width: 100%; height: 600px;"></div>

<script>
// 初始化地图，替换成你需要的默认中心点（纬度、经度）和缩放级别
const map = L.map('map').setView([39.9042, 116.4074], 12);

// 添加我们的自建瓦片图层
const customOsmLayer = L.tileLayer('http://your-server-ip-or-domain/tiles/{z}/{x}/{y}.png', {
    maxZoom: 19, // 改成你在renderd里配置的最大缩放级别，一般是19
    attribution: '© 我的自定义OSM瓦片', // 自定义版权信息，按需修改
    tileSize: 256 // 标准瓦片大小，不用改
}).addTo(map);
</script>

把your-server-ip-or-domain换成你的服务器IP或域名，直接在浏览器里打开这个页面，就能看到你的自建瓦片地图了！

四、我踩过的坑&常见问题排查

瓦片加载不出来？先直接在浏览器访问http://your-server-ip/tiles/10/345/678.png，看返回状态：
- 403错误：肯定是权限问题，再检查/run/renderd和/var/lib/mod_tile的权限设置
- 502错误：renderd没启动，或者Nginx连不上renderd的套接字/端口，检查renderd状态和Nginx配置里的路径
- 空白瓦片：renderd渲染失败，看/var/log/syslog里的错误日志，一般是PostgreSQL连接问题或者Mapnik样式配置错误
瓦片加载慢？预渲染常用的缩放级别，比如批量渲染0到10级：
```
sudo -u renderd render_list -z 0 -Z 10 -a
```
这个命令会提前生成这些级别的瓦片，之后访问这些级别就直接返回缓存，速度飞起
要启用HTTPS？在Nginx配置里加上SSL证书（比如Let's Encrypt的），把listen 80;改成listen 443 ssl;，配置ssl_certificate和ssl_certificate_key路径，然后Leaflet里的URL换成https://就行