簡(jiǎn)介這是一套面向全景內(nèi)容創(chuàng)業(yè)者與開發(fā)者的720全景云系統(tǒng)源碼可生成微信小程序并配套PC端站點(diǎn)適合需要搭建商業(yè)化全景展示平臺(tái)的技術(shù)團(tuán)隊(duì)。系統(tǒng)基于PHP開發(fā)要求云服務(wù)器或獨(dú)立服務(wù)器環(huán)境推薦Linux下Nginx運(yùn)行需PHP5.3、MySQL5.5以上并依賴七?；虬⒗镌芆SS存儲(chǔ)第三方登錄與評(píng)論功能還需認(rèn)證公眾號(hào)接口整體部署門檻高于常見的phpstudy全景通方案。壓縮包共約2000個(gè)文件體積124.5MB以911個(gè)png、193個(gè)gif、47個(gè)jpg等圖片素材和651個(gè)php、249個(gè)js、68個(gè)css等前后端代碼為主另含118個(gè)xml、20個(gè)tpl模板、20個(gè)config配置及krpano相關(guān)批處理與授權(quán)文件覆蓋全景漫游、多分辨率切片、立方體與球面轉(zhuǎn)換等模塊。已有456人學(xué)習(xí)下載可幫助讀者快速獲得一套可二次開發(fā)的全景小程序與PC端完整方案。1. 720全景云系統(tǒng)拆解從源碼包到小程序與PC端落地到底值不值得做手里拿到一個(gè)叫「最新親測(cè)精品720全景云系統(tǒng)可生成小程序帶PC端安裝教程.zip」的包第一反應(yīng)往往不是興奮而是警惕——這類名字里堆滿「精品」「親測(cè)」「帶教程」的壓縮包十個(gè)里有八個(gè)是半成品或者拼湊貨。但720全景這個(gè)方向本身是有真實(shí)需求的房產(chǎn)中介要帶客戶遠(yuǎn)程看房酒店要展示宴會(huì)廳實(shí)景景區(qū)要做線上導(dǎo)覽甚至工廠要遠(yuǎn)程給客戶看車間環(huán)境。全景圖不是新鮮東西但把全景圖做成一套能自己部署、能生成微信小程序、還帶PC端管理后臺(tái)的云系統(tǒng)這個(gè)組合就有落地價(jià)值了。這篇文章要解決的問題很具體拿到這個(gè)包之后怎么判斷它能不能用、怎么把環(huán)境跑起來、怎么生成小程序端、PC端后臺(tái)怎么配、全景圖怎么上傳和管理、最后怎么部署到服務(wù)器讓別人訪問。適合兩類人一類是手里已經(jīng)有這個(gè)包、想自己搭一套全景展示系統(tǒng)的開發(fā)者另一類是正在評(píng)估要不要做類似項(xiàng)目的技術(shù)負(fù)責(zé)人想搞清楚這套東西的技術(shù)棧和落地成本。我不會(huì)假設(shè)你手里有源碼正文所有步驟都按這類全景云系統(tǒng)最常見的架構(gòu)來講你對(duì)照自己的包去驗(yàn)證。2. 環(huán)境準(zhǔn)備與源碼結(jié)構(gòu)跑起來之前先看清目錄里有什么2.1 這類全景云系統(tǒng)的典型技術(shù)棧與目錄結(jié)構(gòu)720全景云系統(tǒng)通常不是單一技術(shù)棧而是「后端API PC管理后臺(tái) 小程序端 全景播放器」四塊拼起來的。后端常見的是 PHPThinkPHP 或 Laravel或者 Node.jsExpress/Koa數(shù)據(jù)庫用 MySQL 5.7 或 8.0PC端后臺(tái)一般是 Vue 2/3 或者 React 打包后的靜態(tài)文件配合 Element UI 或 Ant Design小程序端用微信原生或者 uniapp 編譯全景播放器核心是 Three.js 或者 Pannellum 這類 WebGL 庫負(fù)責(zé)把 equirectangular 全景圖渲染成可拖拽的球面場(chǎng)景。解壓之后你大概率會(huì)看到類似這樣的目錄結(jié)構(gòu)panorama-cloud/ ├── server/ # 后端API │ ├── application/ # 業(yè)務(wù)邏輯ThinkPHP常見 │ ├── config/ # 數(shù)據(jù)庫、緩存配置 │ ├── public/ # 入口文件和上傳目錄 │ └── .env.example # 環(huán)境變量模板 ├── admin/ # PC管理后臺(tái)源碼 │ ├── src/ │ ├── package.json │ └── vue.config.js ├── miniprogram/ # 微信小程序端 │ ├── pages/ │ ├── utils/ │ └── app.json ├── panorama-player/ # 全景播放器可能獨(dú)立或內(nèi)嵌 ├── docs/ # 安裝教程文檔 └── README.md先別急著裝用tree -L 2或者直接看目錄確認(rèn)三件事后端入口文件在哪、數(shù)據(jù)庫SQL文件有沒有、小程序端的app.json里pages列表是否完整。我見過不少包小程序端只給了編譯后的dist沒有源碼這種后期改不動(dòng)直接放棄。2.2 后端環(huán)境搭建PHP/Node MySQL 的最小可跑配置假設(shè)后端是 PHP MySQL 這套最常見的組合。你需要準(zhǔn)備PHP 7.4 或 8.0看composer.json里的要求、MySQL 5.7、Nginx 或 Apache、Composer 包管理器。Windows 下用 phpStudy 或者 Laragon 最快Linux 下用寶塔面板或者手動(dòng)裝。先建數(shù)據(jù)庫導(dǎo)入SQL文件# 登錄MySQL mysql -u root -p # 創(chuàng)建數(shù)據(jù)庫字符集用utf8mb4 CREATE DATABASE panorama_cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; # 導(dǎo)入SQL文件假設(shè)在server目錄下 use panorama_cloud; source /path/to/server/database/panorama_cloud.sql;然后配置后端環(huán)境變量。找到.env.example復(fù)制成.env改數(shù)據(jù)庫連接信息# 進(jìn)入server目錄 cd panorama-cloud/server # 復(fù)制環(huán)境變量模板 cp .env.example .env # 編輯.env重點(diǎn)改這幾項(xiàng) # DB_HOST127.0.0.1 # DB_PORT3306 # DB_DATABASEpanorama_cloud # DB_USERNAMEroot # DB_PASSWORD你的密碼 # APP_DEBUGtrue # 調(diào)試階段先開上線關(guān)掉裝依賴、跑起來# 安裝PHP依賴 composer install # 如果是ThinkPHP設(shè)置public為網(wǎng)站根目錄 # Nginx配置示例 # root /path/to/panorama-cloud/server/public; # index index.php index.html; # 給上傳目錄和緩存目錄寫權(quán)限 chmod -R 755 runtime/ chmod -R 755 public/uploads/訪問http://你的域名或IP/api/或者后臺(tái)入口能看到登錄頁或者JSON返回說明后端通了。如果報(bào)500先看runtime/log下的日志八成是數(shù)據(jù)庫連不上或者PHP擴(kuò)展沒開常見缺fileinfo、gd、curl。2.3 PC管理后臺(tái)的編譯與部署PC端后臺(tái)一般是 Vue 項(xiàng)目需要 Node.js 環(huán)境。版本別用太新的Node 14 或 16 最穩(wěn)Node 18 有時(shí)候老項(xiàng)目會(huì)報(bào) OpenSSL 錯(cuò)誤。# 進(jìn)入admin目錄 cd panorama-cloud/admin # 安裝依賴國內(nèi)建議換淘寶源 npm install --registryhttps://registry.npmmirror.com # 開發(fā)模式跑起來看效果 npm run serve # 生產(chǎn)打包 npm run build打包完會(huì)生成dist目錄把它扔到Nginx的一個(gè)站點(diǎn)下配置反向代理指向后端APIserver { listen 80; server_name admin.yourdomain.com; root /path/to/panorama-cloud/admin/dist; index index.html; location / { try_files $uri $uri/ /index.html; } # 反向代理后端API location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }這里有個(gè)坑很多包的前端請(qǐng)求地址是寫死在代碼里的打包前要改vue.config.js或者.env.production里的VUE_APP_BASE_API指向你的后端域名。不改的話部署上去登錄接口全404。3. 小程序端生成與配置從源碼到能掃碼預(yù)覽3.1 微信小程序端的目錄結(jié)構(gòu)與關(guān)鍵配置項(xiàng)小程序端是整個(gè)系統(tǒng)里最容易翻車的部分因?yàn)槲⑿砰_發(fā)者工具的版本、基礎(chǔ)庫版本、以及小程序的類目審核都會(huì)影響。先看miniprogram目錄核心文件是app.json、app.js、app.wxss以及pages下的各個(gè)頁面。app.json里重點(diǎn)看三個(gè)地方{ pages: [ pages/index/index, pages/panorama/detail, pages/user/user ], window: { navigationBarTitleText: 720全景, navigationBarBackgroundColor: #000000, navigationBarTextStyle: white }, permission: { scope.userLocation: { desc: 用于展示附近的全景場(chǎng)景 } } }pages列表必須和實(shí)際目錄一一對(duì)應(yīng)少一個(gè)頁面就編譯報(bào)錯(cuò)。navigationBarTextStyle只有black和white兩個(gè)值寫錯(cuò)了不報(bào)錯(cuò)但顯示異常。全景展示頁通常需要設(shè)置disableScroll: true因?yàn)槿巴献Ш晚撁鏉L動(dòng)會(huì)沖突。3.2 用微信開發(fā)者工具跑通并生成體驗(yàn)版下載微信開發(fā)者工具穩(wěn)定版即可用微信掃碼登錄。新建項(xiàng)目選擇「導(dǎo)入項(xiàng)目」目錄指向miniprogram文件夾AppID 填你自己的小程序AppID沒有就去微信公眾平臺(tái)注冊(cè)一個(gè)個(gè)人主體也能用。導(dǎo)入后工具會(huì)自動(dòng)編譯。如果報(bào)錯(cuò)按這個(gè)順序排查基礎(chǔ)庫版本在「詳情」→「本地設(shè)置」里把調(diào)試基礎(chǔ)庫調(diào)到 2.19.4 以上太低不支持某些API。域名校驗(yàn)開發(fā)階段在「詳情」→「本地設(shè)置」里勾上「不校驗(yàn)合法域名」否則請(qǐng)求后端接口會(huì)失敗。npm構(gòu)建如果小程序用了 npm 包比如threejs-miniprogram需要點(diǎn)「工具」→「構(gòu)建 npm」。跑通之后點(diǎn)「上傳」填版本號(hào)和備注就生成了體驗(yàn)版。去微信公眾平臺(tái)的「版本管理」里把體驗(yàn)版設(shè)為體驗(yàn)版本掃碼就能在手機(jī)上預(yù)覽。// utils/request.js 里通常封裝了請(qǐng)求 const BASE_URL https://api.yourdomain.com; function request(options) { return new Promise((resolve, reject) { wx.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, header: { content-type: application/json, Authorization: wx.getStorageSync(token) || }, success: (res) { if (res.statusCode 200) { resolve(res.data); } else { reject(res); } }, fail: reject }); }); } module.exports { request };這段代碼的關(guān)鍵是BASE_URL必須改成你自己的后端域名并且這個(gè)域名要在微信公眾平臺(tái)的「開發(fā)管理」→「開發(fā)設(shè)置」→「服務(wù)器域名」里配置好否則正式版請(qǐng)求會(huì)被攔截。開發(fā)階段可以繞過上線前必須配。3.3 全景播放器在小程序里的適配要點(diǎn)小程序里跑全景播放器和H5不一樣。微信小程序不支持直接操作DOMThree.js 需要用threejs-miniprogram這個(gè)適配層或者用微信原生的web-view嵌H5頁面。兩種方案各有取舍方案優(yōu)點(diǎn)缺點(diǎn)threejs-miniprogram原生體驗(yàn)性能好適配成本高部分Three.js特性不支持web-view 嵌H5開發(fā)快播放器直接用現(xiàn)成的需要配置業(yè)務(wù)域名體驗(yàn)略卡如果包里的播放器是基于web-view的你需要在微信公眾平臺(tái)配置業(yè)務(wù)域名并且把H5頁面部署到HTTPS服務(wù)器上。如果是threejs-miniprogram重點(diǎn)檢查canvas的typewebgl是否設(shè)置以及觸摸事件是否綁定了touchstart、touchmove來控制相機(jī)旋轉(zhuǎn)。4. 全景圖上傳、管理與PC端后臺(tái)聯(lián)動(dòng)避坑與排查4.1 全景圖上傳的格式要求與切片處理全景圖不是隨便一張照片就能用。它必須是 equirectangular等距柱狀投影格式寬高比嚴(yán)格 2:1比如 4096×2048、8192×4096。普通手機(jī)拍的廣角照片直接傳上去播放器里會(huì)拉伸變形看著頭暈。上傳前建議做兩件事一是用 PTGui 或者 Hugin 把多張照片拼接成全景圖二是用pano2vr或者krpano做切片生成多級(jí)瓦片這樣加載快。如果系統(tǒng)不支持切片至少要把圖片壓縮到 4096 寬以內(nèi)不然小程序端加載一張 20MB 的圖用戶等半天。后臺(tái)通常有「場(chǎng)景管理」→「添加場(chǎng)景」→「上傳全景圖」的流程。上傳后系統(tǒng)會(huì)生成一個(gè)場(chǎng)景ID小程序端通過這個(gè)ID請(qǐng)求圖片地址。檢查上傳目錄權(quán)限Linux 下public/uploads必須是www用戶可寫否則上傳接口返回500但前端只提示「上傳失敗」查日志才能看到Permission denied。4.2 避坑全景云系統(tǒng)落地時(shí)最容易翻車的5個(gè)點(diǎn)現(xiàn)象1小程序端全景圖加載出來是黑屏只有背景色。原因圖片跨域或者域名沒配。微信小程序請(qǐng)求圖片資源如果圖片域名沒在「downloadFile合法域名」里配置正式版會(huì)靜默失敗。 解決登錄微信公眾平臺(tái)在「開發(fā)設(shè)置」→「服務(wù)器域名」里把圖片存儲(chǔ)的域名加到downloadFile和request合法域名里。開發(fā)階段可以勾「不校驗(yàn)合法域名」臨時(shí)繞過?，F(xiàn)象2PC后臺(tái)登錄后菜單點(diǎn)不動(dòng)控制臺(tái)報(bào)401。原因Token 過期或者請(qǐng)求頭沒帶上。很多包用的是 JWT登錄后存在 localStorage但路由守衛(wèi)里沒正確讀取。 解決打開瀏覽器控制臺(tái)看 Network 里請(qǐng)求的Authorization頭有沒有值。沒有的話檢查登錄邏輯里localStorage.setItem(token, res.data.token)是否執(zhí)行以及 axios 攔截器里是否設(shè)置了config.headers.Authorization?，F(xiàn)象3全景圖拖拽時(shí)頁面跟著滾動(dòng)體驗(yàn)極差。原因觸摸事件沒阻止默認(rèn)行為。H5 里需要e.preventDefault()小程序里需要catchtouchmove而不是bindtouchmove。 解決把播放器容器的觸摸事件從bindtouchmove改成catchtouchmove阻止事件冒泡。H5 里在touchmove回調(diào)里加e.preventDefault()并且 CSS 設(shè)置touch-action: none?，F(xiàn)象4上傳大圖后后端返回成功但數(shù)據(jù)庫里沒有記錄。原因PHP 的upload_max_filesize和post_max_size太小或者 Nginx 的client_max_body_size限制。 解決改php.ini里upload_max_filesize 50M、post_max_size 50M改 Nginx 配置client_max_body_size 50m;重啟服務(wù)。同時(shí)檢查數(shù)據(jù)庫字段類型圖片地址字段別用varchar(255)長URL可能超?，F(xiàn)象5小程序?qū)徍吮痪芴崾尽干婕疤摂M支付」或「類目不符」。原因全景展示如果帶了付費(fèi)看房、會(huì)員解鎖等功能會(huì)被歸到虛擬支付個(gè)人主體小程序不支持。 解決上線前把付費(fèi)相關(guān)功能隱藏或去掉只保留純展示。類目選「工具-效率」或者「商業(yè)服務(wù)-企業(yè)管理服務(wù)」別選「電商平臺(tái)」。4.3 數(shù)據(jù)庫與文件存儲(chǔ)的備份策略全景系統(tǒng)的核心資產(chǎn)是全景圖文件和數(shù)據(jù)庫里的場(chǎng)景配置。圖片文件建議單獨(dú)掛載一塊數(shù)據(jù)盤或者用對(duì)象存儲(chǔ)阿里云OSS、騰訊云COS別和代碼放一個(gè)盤。數(shù)據(jù)庫每天定時(shí)mysqldump# 每天凌晨3點(diǎn)備份保留7天 0 3 * * * mysqldump -u root -p密碼 panorama_cloud /backup/panorama_$(date \%Y\%m\%d).sql find /backup -name panorama_*.sql -mtime 7 -delete對(duì)象存儲(chǔ)的好處是自帶CDN小程序端加載全景圖快很多。如果包里的上傳邏輯是存本地你可以改成存OSS改config/filesystem.php里的驅(qū)動(dòng)配置把local換成oss填上 AccessKey 和 Bucket 信息。5. 部署上線與性能調(diào)優(yōu)讓全景系統(tǒng)真正能對(duì)外服務(wù)5.1 服務(wù)器選型與HTTPS配置全景系統(tǒng)對(duì)帶寬要求不低一張 4096 的全景圖壓縮后大概 2-4MB如果同時(shí)有 10 個(gè)人在看瞬間跑滿 10M 帶寬。建議起步 4核8G、5M 帶寬圖片走對(duì)象存儲(chǔ)CDN服務(wù)器只跑API和后臺(tái)。HTTPS 是必須的微信小程序正式版只允許 HTTPS 請(qǐng)求。用 Lets Encrypt 免費(fèi)證書# 安裝certbot apt install certbot python3-certbot-nginx # 申請(qǐng)證書自動(dòng)改Nginx配置 certbot --nginx -d api.yourdomain.com -d admin.yourdomain.com # 自動(dòng)續(xù)期 certbot renew --dry-run配完 HTTPS 后記得把后端.env里的APP_URL改成https://小程序端的BASE_URL也改成https://否則請(qǐng)求會(huì)被微信攔截。5.2 全景圖加載速度優(yōu)化的3個(gè)手段第一圖片切片。用krpano的makepano工具把全景圖切成多級(jí)瓦片前端按需加載首屏只加載低分辨率預(yù)覽圖。第二開啟 WebP 格式同樣畫質(zhì)下體積比 JPEG 小 30% 左右但要注意小程序基礎(chǔ)庫版本是否支持。第三CDN 緩存把uploads目錄的靜態(tài)資源全部推到 CDN設(shè)置緩存過期時(shí)間 30 天回源只回一次。# Nginx 靜態(tài)資源緩存配置 location ~* \.(jpg|jpeg|png|webp|js|css)$ { expires 30d; add_header Cache-Control public, immutable; }5.3 用 Lighthouse 和微信開發(fā)者工具做上線前驗(yàn)證PC 端用 Chrome 的 Lighthouse 跑一遍重點(diǎn)看 Performance 和 Best Practices全景圖首屏加載時(shí)間控制在 3 秒以內(nèi)算合格。小程序端用微信開發(fā)者工具的「體驗(yàn)評(píng)分」看有沒有 setData 過大、圖片未壓縮、請(qǐng)求并發(fā)過多的問題。我自己的習(xí)慣是上線前一定用真機(jī)跑一遍安卓和 iOS 各測(cè)一臺(tái)。模擬器上全景拖拽流暢真機(jī)上可能因?yàn)?GPU 差異卡頓。特別是 iOSweb-view里的 WebGL 有時(shí)候會(huì)被限制如果發(fā)現(xiàn) iOS 上黑屏試試把播放器換成threejs-miniprogram方案或者降低全景圖分辨率。這套系統(tǒng)值不值得做取決于你的場(chǎng)景。如果只是給客戶展示幾個(gè)全景場(chǎng)景用現(xiàn)成的 SaaS 平臺(tái)更省事但如果要集成到自己的業(yè)務(wù)系統(tǒng)、要數(shù)據(jù)自主可控、要二次開發(fā)那自己部署一套是有長期價(jià)值的。我踩過最大的坑是貪便宜買了 1M 帶寬的服務(wù)器結(jié)果客戶看房時(shí)圖片加載了半分鐘直接打電話投訴。后來換了 5M 帶寬加 CDN才算穩(wěn)住。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取