[{"data":1,"prerenderedAt":843},["ShallowReactive",2],{"doc-page:\u002Fdocs\u002Fnginx-basics":3},{"doc":4,"prev":800,"next":808,"resolvedType":8,"readingMinutes":167,"audience":816,"checklist":820,"related":824},{"path":5,"title":6,"description":7,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":12,"publishedAt":12,"icon":13,"body":14},"\u002Fdocs\u002Fnginx-basics","Nginx 基础配置","Nginx 安装、静态站点、反向代理、HTTPS 配置与性能优化","article",null,"infra-deployment","服务器与部署","2025-11-25","i-carbon-cloud",{"type":15,"value":16,"toc":783},"minimark",[17,21,32,35,40,59,62,82,85,89,130,133,136,288,295,298,381,384,388,535,538,542,617,620,623,670,673,677,696,700,703,707,714,717,728,731,779],[18,19,6],"h1",{"id":20},"nginx-基础配置",[22,23,24,31],"p",{},[25,26,30],"a",{"href":27,"rel":28},"https:\u002F\u002Fnginx.org\u002F",[29],"nofollow","Nginx"," 是高性能的 HTTP 和反向代理服务器。",[22,33,34],{},"这页最适合当作“从 0 到 1 配出可用 Nginx”的起点。很多人第一次接触 Nginx 时最容易混淆的不是语法，而是它到底在当前架构里扮演什么角色。",[36,37,39],"h2",{"id":38},"nginx-常见用途","Nginx 常见用途",[41,42,43,47,50,53,56],"ul",{},[44,45,46],"li",{},"托管静态文件",[44,48,49],{},"反向代理到应用服务",[44,51,52],{},"统一 HTTPS 和域名入口",[44,54,55],{},"缓存静态资源",[44,57,58],{},"为多个站点做虚拟主机分流",[36,60,61],{"id":61},"推荐的上手顺序",[63,64,65,68,76,79],"ol",{},[44,66,67],{},"先跑一个最简单的静态站点",[44,69,70,71,75],{},"再学会把请求反代到 ",[72,73,74],"code",{},"localhost:3000"," 之类的应用服务",[44,77,78],{},"然后补 HTTPS 和 80 → 443 重定向",[44,80,81],{},"最后再做 gzip、缓存、上传大小等优化",[22,83,84],{},"先建立“入口代理”的认知，会比直接背配置块更容易。",[36,86,88],{"id":87},"通过-docker-运行","通过 Docker 运行",[90,91,96],"pre",{"className":92,"code":93,"language":94,"meta":95,"style":95},"language-bash shiki shiki-themes github-light github-dark","docker run -d -p 80:80 --name nginx nginx\n","bash","",[72,97,98],{"__ignoreMap":95},[99,100,103,107,111,115,118,121,124,127],"span",{"class":101,"line":102},"line",1,[99,104,106],{"class":105},"sScJk","docker",[99,108,110],{"class":109},"sZZnC"," run",[99,112,114],{"class":113},"sj4cs"," -d",[99,116,117],{"class":113}," -p",[99,119,120],{"class":109}," 80:80",[99,122,123],{"class":113}," --name",[99,125,126],{"class":109}," nginx",[99,128,129],{"class":109}," nginx\n",[22,131,132],{},"Docker 适合快速试验和本地验证；正式环境还要补卷挂载、配置文件管理、日志和证书目录。",[36,134,135],{"id":135},"静态站点配置",[90,137,141],{"className":138,"code":139,"language":140,"meta":95,"style":95},"language-nginx shiki shiki-themes github-light github-dark","server {\n    listen 80;\n    server_name example.com;\n    root \u002Fusr\u002Fshare\u002Fnginx\u002Fhtml;\n    index index.html;\n\n    location \u002F {\n        try_files $uri $uri\u002F \u002Findex.html;\n    }\n\n    # 缓存静态资源\n    location ~* \\.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ {\n        expires 30d;\n        add_header Cache-Control \"public, immutable\";\n    }\n}\n","nginx",[72,142,143,153,165,174,183,192,199,211,220,226,231,238,252,263,277,282],{"__ignoreMap":95},[99,144,145,149],{"class":101,"line":102},[99,146,148],{"class":147},"szBVR","server",[99,150,152],{"class":151},"sVt8B"," {\n",[99,154,156,159,162],{"class":101,"line":155},2,[99,157,158],{"class":147},"    listen ",[99,160,161],{"class":113},"80",[99,163,164],{"class":151},";\n",[99,166,168,171],{"class":101,"line":167},3,[99,169,170],{"class":147},"    server_name ",[99,172,173],{"class":151},"example.com;\n",[99,175,177,180],{"class":101,"line":176},4,[99,178,179],{"class":147},"    root ",[99,181,182],{"class":151},"\u002Fusr\u002Fshare\u002Fnginx\u002Fhtml;\n",[99,184,186,189],{"class":101,"line":185},5,[99,187,188],{"class":147},"    index ",[99,190,191],{"class":151},"index.html;\n",[99,193,195],{"class":101,"line":194},6,[99,196,198],{"emptyLinePlaceholder":197},true,"\n",[99,200,202,205,208],{"class":101,"line":201},7,[99,203,204],{"class":147},"    location",[99,206,207],{"class":105}," \u002F ",[99,209,210],{"class":151},"{\n",[99,212,214,217],{"class":101,"line":213},8,[99,215,216],{"class":147},"        try_files ",[99,218,219],{"class":151},"$uri $uri\u002F \u002Findex.html;\n",[99,221,223],{"class":101,"line":222},9,[99,224,225],{"class":151},"    }\n",[99,227,229],{"class":101,"line":228},10,[99,230,198],{"emptyLinePlaceholder":197},[99,232,234],{"class":101,"line":233},11,[99,235,237],{"class":236},"sJ8bj","    # 缓存静态资源\n",[99,239,241,243,246,250],{"class":101,"line":240},12,[99,242,204],{"class":147},[99,244,245],{"class":147}," ~*",[99,247,249],{"class":248},"sA_wV"," \\.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ ",[99,251,210],{"class":151},[99,253,255,258,261],{"class":101,"line":254},13,[99,256,257],{"class":147},"        expires ",[99,259,260],{"class":113},"30d",[99,262,164],{"class":151},[99,264,266,269,272,275],{"class":101,"line":265},14,[99,267,268],{"class":147},"        add_header ",[99,270,271],{"class":151},"Cache-Control ",[99,273,274],{"class":109},"\"public, immutable\"",[99,276,164],{"class":151},[99,278,280],{"class":101,"line":279},15,[99,281,225],{"class":151},[99,283,285],{"class":101,"line":284},16,[99,286,287],{"class":151},"}\n",[22,289,290,291,294],{},"这是最常见的 SPA \u002F 静态文档站配置思路，",[72,292,293],{},"try_files"," 能避免刷新子路由时报 404。",[36,296,297],{"id":297},"反向代理",[90,299,301],{"className":138,"code":300,"language":140,"meta":95,"style":95},"server {\n    listen 80;\n    server_name api.example.com;\n\n    location \u002F {\n        proxy_pass http:\u002F\u002Flocalhost:3000;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n}\n",[72,302,303,309,317,324,328,336,344,352,359,366,373,377],{"__ignoreMap":95},[99,304,305,307],{"class":101,"line":102},[99,306,148],{"class":147},[99,308,152],{"class":151},[99,310,311,313,315],{"class":101,"line":155},[99,312,158],{"class":147},[99,314,161],{"class":113},[99,316,164],{"class":151},[99,318,319,321],{"class":101,"line":167},[99,320,170],{"class":147},[99,322,323],{"class":151},"api.example.com;\n",[99,325,326],{"class":101,"line":176},[99,327,198],{"emptyLinePlaceholder":197},[99,329,330,332,334],{"class":101,"line":185},[99,331,204],{"class":147},[99,333,207],{"class":105},[99,335,210],{"class":151},[99,337,338,341],{"class":101,"line":194},[99,339,340],{"class":147},"        proxy_pass ",[99,342,343],{"class":151},"http:\u002F\u002Flocalhost:3000;\n",[99,345,346,349],{"class":101,"line":201},[99,347,348],{"class":147},"        proxy_set_header ",[99,350,351],{"class":151},"Host $host;\n",[99,353,354,356],{"class":101,"line":213},[99,355,348],{"class":147},[99,357,358],{"class":151},"X-Real-IP $remote_addr;\n",[99,360,361,363],{"class":101,"line":222},[99,362,348],{"class":147},[99,364,365],{"class":151},"X-Forwarded-For $proxy_add_x_forwarded_for;\n",[99,367,368,370],{"class":101,"line":228},[99,369,348],{"class":147},[99,371,372],{"class":151},"X-Forwarded-Proto $scheme;\n",[99,374,375],{"class":101,"line":233},[99,376,225],{"class":151},[99,378,379],{"class":101,"line":240},[99,380,287],{"class":151},[22,382,383],{},"绝大多数 Node、Python、Go Web 服务部署到公网时，都会在前面放一层这样的 Nginx。",[36,385,387],{"id":386},"https-配置lets-encrypt","HTTPS 配置（Let's Encrypt）",[90,389,391],{"className":138,"code":390,"language":140,"meta":95,"style":95},"server {\n    listen 443 ssl http2;\n    server_name example.com;\n\n    ssl_certificate \u002Fetc\u002Fletsencrypt\u002Flive\u002Fexample.com\u002Ffullchain.pem;\n    ssl_certificate_key \u002Fetc\u002Fletsencrypt\u002Flive\u002Fexample.com\u002Fprivkey.pem;\n    ssl_protocols TLSv1.2 TLSv1.3;\n    ssl_prefer_server_ciphers on;\n\n    location \u002F {\n        root \u002Fusr\u002Fshare\u002Fnginx\u002Fhtml;\n        try_files $uri $uri\u002F \u002Findex.html;\n    }\n}\n\n# HTTP 重定向到 HTTPS\nserver {\n    listen 80;\n    server_name example.com;\n    return 301 https:\u002F\u002F$server_name$request_uri;\n}\n",[72,392,393,399,409,415,419,427,435,443,453,457,465,472,478,482,486,490,495,502,511,518,530],{"__ignoreMap":95},[99,394,395,397],{"class":101,"line":102},[99,396,148],{"class":147},[99,398,152],{"class":151},[99,400,401,403,406],{"class":101,"line":155},[99,402,158],{"class":147},[99,404,405],{"class":113},"443",[99,407,408],{"class":151}," ssl http2;\n",[99,410,411,413],{"class":101,"line":167},[99,412,170],{"class":147},[99,414,173],{"class":151},[99,416,417],{"class":101,"line":176},[99,418,198],{"emptyLinePlaceholder":197},[99,420,421,424],{"class":101,"line":185},[99,422,423],{"class":147},"    ssl_certificate ",[99,425,426],{"class":151},"\u002Fetc\u002Fletsencrypt\u002Flive\u002Fexample.com\u002Ffullchain.pem;\n",[99,428,429,432],{"class":101,"line":194},[99,430,431],{"class":147},"    ssl_certificate_key ",[99,433,434],{"class":151},"\u002Fetc\u002Fletsencrypt\u002Flive\u002Fexample.com\u002Fprivkey.pem;\n",[99,436,437,440],{"class":101,"line":201},[99,438,439],{"class":147},"    ssl_protocols ",[99,441,442],{"class":151},"TLSv1.2 TLSv1.3;\n",[99,444,445,448,451],{"class":101,"line":213},[99,446,447],{"class":147},"    ssl_prefer_server_ciphers ",[99,449,450],{"class":113},"on",[99,452,164],{"class":151},[99,454,455],{"class":101,"line":222},[99,456,198],{"emptyLinePlaceholder":197},[99,458,459,461,463],{"class":101,"line":228},[99,460,204],{"class":147},[99,462,207],{"class":105},[99,464,210],{"class":151},[99,466,467,470],{"class":101,"line":233},[99,468,469],{"class":147},"        root ",[99,471,182],{"class":151},[99,473,474,476],{"class":101,"line":240},[99,475,216],{"class":147},[99,477,219],{"class":151},[99,479,480],{"class":101,"line":254},[99,481,225],{"class":151},[99,483,484],{"class":101,"line":265},[99,485,287],{"class":151},[99,487,488],{"class":101,"line":279},[99,489,198],{"emptyLinePlaceholder":197},[99,491,492],{"class":101,"line":284},[99,493,494],{"class":236},"# HTTP 重定向到 HTTPS\n",[99,496,498,500],{"class":101,"line":497},17,[99,499,148],{"class":147},[99,501,152],{"class":151},[99,503,505,507,509],{"class":101,"line":504},18,[99,506,158],{"class":147},[99,508,161],{"class":113},[99,510,164],{"class":151},[99,512,514,516],{"class":101,"line":513},19,[99,515,170],{"class":147},[99,517,173],{"class":151},[99,519,521,524,527],{"class":101,"line":520},20,[99,522,523],{"class":147},"    return",[99,525,526],{"class":113}," 301",[99,528,529],{"class":151}," https:\u002F\u002F$server_name$request_uri;\n",[99,531,533],{"class":101,"line":532},21,[99,534,287],{"class":151},[22,536,537],{},"证书配置不是“部署完成后再想”的附加项，公网服务建议一开始就纳入部署流程。",[36,539,541],{"id":540},"进阶性能优化","进阶：性能优化",[90,543,545],{"className":138,"code":544,"language":140,"meta":95,"style":95},"# 在 http 块中添加\ngzip on;\ngzip_vary on;\ngzip_min_length 1024;\ngzip_types text\u002Fplain text\u002Fcss application\u002Fjson application\u002Fjavascript text\u002Fxml;\n\n# 连接优化\nkeepalive_timeout 65;\nclient_max_body_size 50m;\n",[72,546,547,552,561,570,580,588,592,597,607],{"__ignoreMap":95},[99,548,549],{"class":101,"line":102},[99,550,551],{"class":236},"# 在 http 块中添加\n",[99,553,554,557,559],{"class":101,"line":155},[99,555,556],{"class":147},"gzip ",[99,558,450],{"class":113},[99,560,164],{"class":151},[99,562,563,566,568],{"class":101,"line":167},[99,564,565],{"class":147},"gzip_vary ",[99,567,450],{"class":113},[99,569,164],{"class":151},[99,571,572,575,578],{"class":101,"line":176},[99,573,574],{"class":147},"gzip_min_length ",[99,576,577],{"class":113},"1024",[99,579,164],{"class":151},[99,581,582,585],{"class":101,"line":185},[99,583,584],{"class":147},"gzip_types ",[99,586,587],{"class":151},"text\u002Fplain text\u002Fcss application\u002Fjson application\u002Fjavascript text\u002Fxml;\n",[99,589,590],{"class":101,"line":194},[99,591,198],{"emptyLinePlaceholder":197},[99,593,594],{"class":101,"line":201},[99,595,596],{"class":236},"# 连接优化\n",[99,598,599,602,605],{"class":101,"line":213},[99,600,601],{"class":147},"keepalive_timeout ",[99,603,604],{"class":113},"65",[99,606,164],{"class":151},[99,608,609,612,615],{"class":101,"line":222},[99,610,611],{"class":147},"client_max_body_size ",[99,613,614],{"class":113},"50m",[99,616,164],{"class":151},[22,618,619],{},"不要盲目复制网上大段“性能优化模板”。对小站点来说，先保证配置可读、可维护，比堆很多指令更重要。",[36,621,622],{"id":622},"常用命令",[90,624,626],{"className":92,"code":625,"language":94,"meta":95,"style":95},"nginx -t          # 测试配置\nnginx -s reload   # 重载配置\nnginx             # 启动\nnginx -s stop     # 停止\n",[72,627,628,638,651,658],{"__ignoreMap":95},[99,629,630,632,635],{"class":101,"line":102},[99,631,140],{"class":105},[99,633,634],{"class":113}," -t",[99,636,637],{"class":236},"          # 测试配置\n",[99,639,640,642,645,648],{"class":101,"line":155},[99,641,140],{"class":105},[99,643,644],{"class":113}," -s",[99,646,647],{"class":109}," reload",[99,649,650],{"class":236},"   # 重载配置\n",[99,652,653,655],{"class":101,"line":167},[99,654,140],{"class":105},[99,656,657],{"class":236},"             # 启动\n",[99,659,660,662,664,667],{"class":101,"line":176},[99,661,140],{"class":105},[99,663,644],{"class":113},[99,665,666],{"class":109}," stop",[99,668,669],{"class":236},"     # 停止\n",[36,671,672],{"id":672},"常见问题",[674,675,676],"h3",{"id":676},"配置改了不生效",[41,678,679,686,689],{},[44,680,681,682,685],{},"先执行 ",[72,683,684],{},"nginx -t"," 看是否有语法错误",[44,687,688],{},"再确认你修改的是实际加载的配置文件",[44,690,691,692,695],{},"最后执行 ",[72,693,694],{},"reload"," 而不是只改文件不重载",[674,697,699],{"id":698},"访问域名返回-502","访问域名返回 502",[22,701,702],{},"大多数时候是后端服务没启动、端口写错，或 Nginx 根本连不到上游服务。先排查应用本身，再看代理配置。",[674,704,706],{"id":705},"刷新前端路由-404","刷新前端路由 404",[22,708,709,710,713],{},"通常是静态站点没加 ",[72,711,712],{},"try_files $uri $uri\u002F \u002Findex.html;","。",[36,715,716],{"id":716},"推荐联动阅读",[41,718,719,722,725],{},[44,720,721],{},"先看 Nginx 基础配置",[44,723,724],{},"再看 HTTPS \u002F SSL 自动化",[44,726,727],{},"最后结合具体应用（Nuxt、Node API、Docker 服务）做项目化落地",[36,729,730],{"id":730},"参考链接",[41,732,733,740,748,756,764,772],{},[44,734,735,739],{},[25,736,738],{"href":27,"rel":737},[29],"Nginx 官网"," — 下载与文档",[44,741,742,747],{},[25,743,746],{"href":744,"rel":745},"https:\u002F\u002Fgithub.com\u002Fnginx\u002Fnginx",[29],"Nginx GitHub"," — 源码",[44,749,750,755],{},[25,751,754],{"href":752,"rel":753},"https:\u002F\u002Fletsencrypt.org\u002F",[29],"Let's Encrypt"," — 免费 SSL 证书",[44,757,758,763],{},[25,759,762],{"href":760,"rel":761},"https:\u002F\u002Fcertbot.eff.org\u002F",[29],"Certbot"," — 自动化证书管理",[44,765,766,771],{},[25,767,770],{"href":768,"rel":769},"https:\u002F\u002Fwww.digitalocean.com\u002Fcommunity\u002Ftools\u002Fnginx",[29],"Nginx 配置生成器"," — DigitalOcean 工具",[44,773,774,778],{},[25,775,777],{"href":776},"\u002Fdocs\u002Fcertbot-ssl","Certbot \u002F SSL 配置"," — 证书自动化与续期更细节的说明",[780,781,782],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .sA_wV, html code.shiki .sA_wV{--shiki-default:#032F62;--shiki-dark:#DBEDFF}",{"title":95,"searchDepth":155,"depth":155,"links":784},[785,786,787,788,789,790,791,792,793,798,799],{"id":38,"depth":155,"text":39},{"id":61,"depth":155,"text":61},{"id":87,"depth":155,"text":88},{"id":135,"depth":155,"text":135},{"id":297,"depth":155,"text":297},{"id":386,"depth":155,"text":387},{"id":540,"depth":155,"text":541},{"id":622,"depth":155,"text":622},{"id":672,"depth":155,"text":672,"children":794},[795,796,797],{"id":676,"depth":167,"text":676},{"id":698,"depth":167,"text":699},{"id":705,"depth":167,"text":706},{"id":716,"depth":155,"text":716},{"id":730,"depth":155,"text":730},{"path":801,"title":802,"description":803,"docType":8,"resourceKind":9,"categoryId":804,"categoryLabel":805,"updatedAt":806,"publishedAt":806,"icon":807},"\u002Fdocs\u002Fpowertoys-guide","PowerToys 实用工具集","微软 PowerToys 各模块功能介绍、使用技巧与推荐配置","windows-system","Windows 系统","2025-11-30","i-mdi-microsoft-windows",{"path":809,"title":810,"description":811,"docType":8,"resourceKind":9,"categoryId":812,"categoryLabel":813,"updatedAt":814,"publishedAt":814,"icon":815},"\u002Fdocs\u002Fmise-guide","mise 多语言版本管理","用 mise 统一管理 Node.js、Python、Rust、Go 等运行时，以及项目级工具链配置","dev-environment","开发环境","2025-11-14","i-carbon-code",[817,818,819],"希望把零散经验整理成长期可复用工作流的人","想先建立认知，再决定是否深入实践的人","希望阅读时顺手建立自己的操作清单或收藏体系的人",[821,822,823],"先浏览标题、摘要和目录，带着问题阅读会更高效","顺手记录真正对你有用的命令、链接和注意事项，避免重复搜索","如果页面里提到相关文档，尽量一起打开对照，效果通常更完整",[825,830,834,839],{"path":826,"title":827,"description":828,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":829,"publishedAt":829,"icon":13},"\u002Fdocs\u002Fcloudflare-pages-deploy","Cloudflare Pages 部署指南","Cloudflare Pages 项目部署、自定义域名、环境变量、重定向与 Functions","2026-02-28",{"path":831,"title":832,"description":833,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":829,"publishedAt":829,"icon":13},"\u002Fdocs\u002Fs3-storage","S3 对象存储","S3 兼容存储使用、Cloudflare R2、MinIO 自建、rclone 同步与 SDK 集成",{"path":835,"title":836,"description":837,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":838,"publishedAt":838,"icon":13},"\u002Fdocs\u002Fmonitoring-logging","监控与日志","服务器监控工具、日志管理、Uptime 监控与告警配置","2026-02-27",{"path":840,"title":841,"description":842,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":838,"publishedAt":838,"icon":13},"\u002Fdocs\u002Fcontainer-orchestration","容器编排入门","Docker Swarm 与 Kubernetes 基础概念、常用命令与本地开发环境",1776215713525]