uniApp H5项目从打包到上线：一站式解决跨域与Nginx部署

1. uniApp H5项目打包全流程解析第一次用uniApp打包H5项目时我对着空白页面和404错误整整折腾了两天。后来才发现问题出在基础路径配置这个看似简单的环节上。uniApp打包H5和传统Vue项目有些不同这里我把踩过的坑都总结成可复用的经验。打包前需要重点关注manifest.json中的H5配置模块。点击HBuilderX编辑器左侧的manifest.json文件切换到源码视图你会看到类似这样的结构h5: { router: { base: ./ }, publicPath: , template: public/index.html }这里router.base就是项目运行的根路径相当于Vue CLI中的publicPath。我建议在项目初期就确定好这个值通常有三种常见配置方案根目录部署比如直接放在nginx的html目录下配置为./子目录部署比如/usr/local/nginx/html/project_name/配置为/project_name/CDN部署需要配置完整的URL路径实际部署时最容易出错的是路径不一致问题。我遇到过最典型的情况是本地开发正常部署后静态资源加载404。这时候需要检查三个地方是否统一manifest.json中的router.base配置服务器上存放静态文件的目录名浏览器访问的URL路径打包操作本身很简单在HBuilderX顶部菜单选择发行→网站-H5手机版。但在网站域名栏要特别注意这里填的是生产环境访问地址比如https://yourdomain.com。如果填错会导致资源路径错误这个配置会直接影响打包生成的index.html中资源引用路径。2. 跨域问题的两种解决方案本地开发时最头疼的就是跨域问题。第一次对接后端API时我对着浏览器的CORS错误提示束手无策直到发现uniApp自带的代理配置方案。在manifest.json中添加devServer配置可以完美解决开发环境跨域h5: { devServer: { proxy: { /api: { target: http://your-api-server.com, changeOrigin: true, pathRewrite: {^/api: } } } } }这个配置的意思是把所有以/api开头的请求转发到target指定的服务器并去掉/api前缀。实际项目请求时这样写uni.request({ url: /api/user/login, method: POST, success: (res) { console.log(res.data) } })但要注意这仅适用于开发环境很多新手会误以为这样配置后生产环境也能用其实生产环境必须通过Nginx解决跨域。我曾犯过一个低级错误在测试环境正常后直接部署结果生产环境所有接口都报404就是因为没配置Nginx反向代理。3. Nginx生产环境配置详解第一次登录服务器配置Nginx时面对密密麻麻的配置项简直头皮发麻。后来我发现只需要关注几个关键配置就能让H5项目跑起来。找到Nginx配置文件通常在/etc/nginx/nginx.conf或/usr/local/nginx/conf/nginx.conf在server块中添加以下配置server { listen 80; server_name yourdomain.com; location / { root /usr/local/nginx/html/your-project; index index.html; try_files $uri $uri/ /index.html; } location /api { proxy_pass http://api-server.com; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这个配置做了三件重要的事将域名根目录指向你的H5项目文件夹配置history路由模式支持try_files指令设置/api前缀的接口代理到后端服务配置完成后执行nginx -s reload使配置生效。有个常见陷阱是文件权限问题——记得用chmod -R 755 /usr/local/nginx/html/your-project给项目目录赋权否则可能出现403 Forbidden错误。4. HTTPS安全部署最佳实践去年我接手的一个项目因为没配置HTTPS导致用户数据被劫持这个教训让我深刻认识到安全部署的重要性。用Certbot申请Lets Encrypt免费证书其实很简单sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d yourdomain.com然后在Nginx配置中强制HTTPS跳转server { listen 80; server_name yourdomain.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name yourdomain.com; ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; # 其他配置... }配置HTTPS后记得在manifest.json中把请求协议都改为https否则会出现混合内容警告。有个容易忽略的细节是WebSocket连接也需要走wss协议我在实时聊天功能上就栽过跟头。5. 性能优化实战技巧项目上线后用户反馈页面加载慢通过Chrome DevTools分析发现主要瓶颈在静态资源加载。经过几轮优化总结出这些有效方案开启Nginx gzip压缩gzip on; gzip_types text/plain text/css application/json application/javascript text/xml;配置静态资源缓存location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { expires 365d; add_header Cache-Control public, no-transform; }在uniApp打包时开启代码压缩h5: { optimization: { treeShaking: true } }使用uni-app的subpackages分包加载功能subPackages: [ { root: pages/sub1, pages: [index, detail] } ]实测下来这些优化能让首屏加载时间减少60%以上。有个反直觉的发现过长的缓存时间反而会导致更新困难后来我们采用文件名hash策略解决了这个问题。6. 常见问题排查指南凌晨两点被紧急电话叫醒处理线上故障的经历让我养成了写问题排查手册的习惯。以下是几个高频问题的解决方案问题一页面刷新后404原因Nginx未配置history路由回退 解决确保有try_files配置location / { try_files $uri $uri/ /index.html; }问题二静态资源路径错误现象控制台报错找不到js/css文件 解决检查三步一致性manifest.json中的publicPath服务器实际文件路径Nginx配置的root路径问题三接口请求跨域现象生产环境接口报CORS错误 解决Nginx添加CORS头location /api { add_header Access-Control-Allow-Origin $http_origin; add_header Access-Control-Allow-Methods GET,POST,OPTIONS; add_header Access-Control-Allow-Headers Content-Type; }问题四iOS白屏现象iOS Safari打开空白但Android正常 解决检查babel配置确保ES6语法正确转译并确认未使用iOS不支持的API每次部署新版本前我都会用这个检查清单走一遍流程线上事故率直接降了90%。特别提醒修改Nginx配置后一定要用nginx -t测试语法正确性有次我因为少了个分号导致整个服务不可用。