从开发到上线：手把手教你用uniApp + Nginx搞定H5项目全链路部署（实战篇）
当你完成了一个令人兴奋的uniApp H5项目开发，接下来面临的最大挑战就是如何让它真正"活"起来——从本地开发环境走向公网可访问的生产环境。这个过程看似简单，实则暗藏玄机：为什么打包后的H5项目不能直接双击打开？如何选择服务器目录结构？Nginx配置中的每个参数究竟起什么作用？本文将带你完整走通这条部署之路，避开那些新手常踩的坑。
1. 项目打包：从开发环境到生产代码
在开始部署之前，我们需要将uniApp项目转换为浏览器可理解的静态资源。这不仅仅是简单的打包操作，更关系到后续部署的成败。
1.1 配置生产环境参数
在manifest.json中，有几个关键配置直接影响打包结果：
{ "h5": { "router": { "mode": "history", // 使用history路由模式 "base": "/" // 部署的基础路径 }, "publicPath": "/", // 静态资源路径 "devServer": { "proxy": {} // 开发环境代理配置（不影响生产） } } }注意：
publicPath如果设置为相对路径(如./)，在部署到子目录时会导致资源加载失败，建议始终使用绝对路径。
1.2 执行打包命令
在项目根目录运行：
npm run build:h5这将生成/dist/build/h5目录，包含以下关键文件：
├── index.html # 应用入口 ├── static │ ├── css # 样式文件 │ ├── js # 脚本文件 │ └── media # 图片等媒体资源 └── favicon.ico # 网站图标常见问题排查：
- 如果打包后页面空白，检查是否使用了动态加载的第三方库
- 图片资源404通常是由于路径引用方式不当导致
- 路由跳转失效可能是history模式未正确配置
2. 服务器准备：构建部署的基础设施
2.1 服务器连接与目录规划
使用SSH连接服务器后，建议采用以下目录结构：
/home └── projects └── your-project ├── current # 当前版本软链接 ├── releases # 版本历史 │ └── v1.0.0 # 具体版本目录 └── shared # 共享资源（如上传目录）使用Xftp等工具上传文件时，注意：
- 保持本地与服务器目录结构一致
- 传输模式选择"二进制"（避免脚本文件损坏）
- 首次上传建议压缩为zip包，在服务器解压
2.2 基础环境检查
确保服务器已安装必要组件：
# 检查Nginx版本 nginx -v # 检查Node.js环境（如需服务端渲染） node -v # 检查防火墙状态 sudo ufw status3. Nginx配置：让项目真正可访问
3.1 基础服务配置
在/etc/nginx/conf.d/your-project.conf中创建配置文件：
server { listen 80; server_name your-domain.com; root /home/projects/your-project/current; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend-service; proxy_set_header Host $host; } }关键参数解析：
| 配置项 | 作用说明 | 典型值示例 |
|---|---|---|
try_files | 处理前端路由回退 | $uri $uri/ /index.html |
gzip | 启用压缩减少传输体积 | gzip on; |
client_max_body_size | 调整上传文件大小限制 | 20m; |
3.2 跨域处理方案
当需要对接不同域名的API时，可采用以下策略：
- Nginx反向代理（推荐）
location /api/ { proxy_pass https://api.target.com/; proxy_set_header Origin ""; add_header 'Access-Control-Allow-Origin' $http_origin; }- JSONP方案（仅限GET请求）
function jsonp(url, callback) { const script = document.createElement('script'); script.src = `${url}?callback=${callback}`; document.body.appendChild(script); }- CORS配置（需后端配合）
add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';4. 部署优化：提升生产环境稳定性
4.1 自动化部署脚本
创建deploy.sh实现一键部署：
#!/bin/bash # 定义变量 VERSION="1.0.$(date +%s)" RELEASE_DIR="/home/projects/your-project/releases/$VERSION" # 创建新版本目录 mkdir -p $RELEASE_DIR # 上传并解压新版本（实际场景中可能是git pull或rsync） unzip -q your-project.zip -d $RELEASE_DIR # 切换当前版本软链接 ln -sfn $RELEASE_DIR /home/projects/your-project/current # 重启Nginx sudo systemctl restart nginx echo "Deployed version $VERSION"4.2 性能调优建议
- 启用HTTP/2：
listen 443 ssl http2;- 配置缓存策略：
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { expires 30d; add_header Cache-Control "public, no-transform"; }- 启用Brotli压缩：
brotli on; brotli_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;5. 安全加固：保护你的线上应用
5.1 基础安全配置
# 禁用服务器信息暴露 server_tokens off; # 防止点击劫持 add_header X-Frame-Options "SAMEORIGIN"; # XSS防护 add_header X-XSS-Protection "1; mode=block"; # 内容安全策略（根据实际调整） add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' cdn.example.com;";5.2 HTTPS配置最佳实践
使用Let's Encrypt免费证书：
sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.com自动续期配置：
# 编辑crontab 0 12 * * * /usr/bin/certbot renew --quietNginx的SSL配置优化：
ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256...'; ssl_session_timeout 1d; ssl_session_cache shared:SSL:50m;6. 监控与维护：确保长期稳定运行
6.1 基础监控设置
使用Nginx内置状态页：
location /nginx_status { stub_status on; access_log off; allow 127.0.0.1; deny all; }输出示例：
Active connections: 3 server accepts handled requests 100 100 200 Reading: 0 Writing: 1 Waiting: 26.2 日志分析策略
配置日志格式：
log_format main '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" ' '$request_time $upstream_response_time';定期分析命令：
# 统计HTTP状态码 awk '{print $9}' access.log | sort | uniq -c | sort -rn # 找出响应最慢的请求 awk '{print $1, $NF}' access.log | sort -k2 -rn | head -20在实际项目中，最容易被忽视的是Nginx的client_max_body_size配置——当你的应用需要上传文件时，默认的1MB限制会导致大文件上传失败。另一个常见陷阱是history路由模式下的404问题，这需要通过正确的try_files配置来解决。
