7d68cbdffa
* docs: improve deployment troubleshooting docs * docs: fix GitHub casing in FAQ * docs: clarify subdomain address creation
7.6 KiB
Cloudflare Pages Frontend
<script setup> import { ref } from 'vue' import JSZip from 'jszip'; const domain = ref("") const downloadUrl = ref("") const tip = ref("Download") const errorMessage = ref("") const resetDownloadUrl = () => { if (!downloadUrl.value) { return } window.URL.revokeObjectURL(downloadUrl.value) downloadUrl.value = "" } const validateDomain = (value) => { const normalizedValue = value.trim() if (!normalizedValue) { return "Please enter a backend API URL starting with https://" } if (/\s/.test(normalizedValue)) { return "The backend API URL must not contain whitespace characters" } if (!normalizedValue.startsWith("https://")) { return "The backend API URL must start with https://" } if (normalizedValue.endsWith("/")) { return "Do not add a trailing / to the backend API URL" } try { const url = new URL(normalizedValue) if (url.protocol !== "https:") { return "The backend API URL must start with https://" } if (url.pathname !== "/" || url.search || url.hash) { return "Please enter the backend API root URL only, without a path, query, or hash" } } catch { return "The backend API URL format is invalid" } return "" } const generate = async () => { const normalizedDomain = domain.value.trim() const validationError = validateDomain(normalizedDomain) errorMessage.value = validationError resetDownloadUrl() if (validationError) { return } domain.value = normalizedDomain let timeoutId = 0 try { const controller = new AbortController() timeoutId = window.setTimeout(() => controller.abort(), 10000) const response = await fetch("/ui_install/frontend.zip", { signal: controller.signal }); if (!response.ok) { errorMessage.value = "Failed to download the frontend zip file. Please try again later" return } const arrayBuffer = await response.arrayBuffer(); var zip = new JSZip(); await zip.loadAsync(arrayBuffer); let target_path = "" const directory = zip.folder("assets"); if (directory) { for (const [relativePath, zipEntry] of Object.entries(directory.files)) { console.log(relativePath); if (relativePath.startsWith("assets/index-") && relativePath.endsWith(".js")){ let content = await zipEntry.async("string"); content = content.replaceAll("https://temp-email-api.xxx.xxx", normalizedDomain); target_path = relativePath; zip.file(relativePath, content); break; } } } if (!target_path) { errorMessage.value = "Could not find the frontend entry file. Generation failed" return } const blob = await zip.generateAsync({ type: "blob" }); const url = window.URL.createObjectURL(blob); errorMessage.value = "" downloadUrl.value = url; } catch (error) { console.error("Error: ", error); if (error instanceof DOMException && error.name === "AbortError") { errorMessage.value = "Download timed out. Please refresh the page and try again" return } errorMessage.value = "Generation failed. Please refresh the page and try again" } finally { window.clearTimeout(timeoutId) } } </script>-
Click
Compute (Workers)->Workers & Pages->Create
-
Select
Pages, chooseUse direct upload
-
Enter the deployed worker address. It must be the backend API root URL, start with
https://, and must not include a trailing/. Click generate, and if successful, a download button will appear. You will get a zip package.- The worker domain here is the backend API domain. For example, if I deployed at
https://temp-email-api.awsl.uk, then fill inhttps://temp-email-api.awsl.uk - If your domain is
https://temp-email-api.xxx.workers.dev, then fill inhttps://temp-email-api.xxx.workers.dev - Do not enter your frontend
Pagesdomain, and do not include paths like/adminor/api. Otherwise frontend requests will hit the wrong address and you may seeCannot read properties of undefined (reading 'map')or405 Method Not Allowed - Before filling it in, open
https://your-worker-domain/open_api/settingsin the browser and confirm it returns JSON. If it returns HTML, 404, 405, or a Cloudflare challenge page, fix the Worker binding, variables, or security policy first
[!warning] Note The
worker.devdomain is not accessible in China, please use a custom domain.Do not enable security policies such as Under Attack, Bot Fight, or Managed Challenge on the backend API domain. Frontend XHR requests cannot complete those browser challenges, and the common symptom is
Network Error.Generate {{ tip }}Example: `https://temp-email-api.example.com`. Do not enter the frontend Pages domain and do not add a trailing `/`.
{{ errorMessage }}
Note
You can also deploy manually. Download the zip from here: frontend.zip
Modify the index-xxx.js file in the archive, where xx is a random string
Search for
https://temp-email-api.xxx.xxxand replace it with your worker's backend API root URL, then deploy the new zip file. If you replace it with the frontend Pages domain, common symptoms are themaperror or405responses from API requestsIf you entered the wrong address the first time and still see errors after redeploying, test in an incognito window or clear browser cache so the browser stops using the old frontend assets.
- The worker domain here is the backend API domain. For example, if I deployed at
-
Select
Pages, clickCreate Pages, modify the name, upload the downloaded zip package[!warning] Important: SPA Mode This project is a Single-Page Application (SPA). You must expand the advanced options during deployment and set "Not Found handling" to
Single-page application (SPA). Otherwise, refreshing the page or directly accessing sub-paths like/adminwill return a 404 error.
Then click
Deploy
-
Open the
Pagesyou just deployed, clickCustom Domain. Here you can add your own domain, or you can use the automatically generated*.pages.devdomain. If you can open the domain, the deployment is successful.
