1 · Words 2 · Build it 3 · GitHub 4 · clasp 5 · Sources

🌐 Google Sites Lab

A Google Site is a container. It shows things beautifully and it runs no code of yours — no server, no database, no custom JavaScript on the page itself. That single fact is the whole lesson. Everything dynamic you have ever seen on a Google Site is a second machine — an Apps Script Web App, or an embedded page — showing through a window in the Site. 谷歌网站是一个容器。它把内容展示得很漂亮，但它不运行你写的任何代码——没有服务器、没有数据库，页面本身也不跑你的 JavaScript。这一个事实就是整堂课的重点。你在谷歌网站上见过的所有动态效果，都是第二台机器——一个应用脚本网络应用，或者一个被嵌入的页面——透过窗口显示出来的。 กูเกิลไซต์คือภาชนะ มันแสดงเนื้อหาได้สวยงาม แต่มันไม่รันโค้ดของคุณเลย ไม่มีเซิร์ฟเวอร์ ไม่มีฐานข้อมูล และไม่รัน JavaScript ของคุณบนหน้าเว็บนั้นเอง ข้อเท็จจริงข้อเดียวนี้คือแก่นของบทเรียนทั้งหมด ทุกสิ่งที่เคลื่อนไหวได้ซึ่งคุณเคยเห็นบนกูเกิลไซต์ ล้วนเป็นเครื่องที่สอง คือเว็บแอปแอปส์สคริปต์ หรือหน้าเว็บที่ถูกฝังไว้ ซึ่งแสดงผลผ่านหน้าต่างบานหนึ่ง

This lab builds both machines, wires them together with a Google Sheet as the database, and then puts the whole thing under version control so it deploys from GitHub. 这个实验室会把两台机器都搭起来，用一个谷歌表格当数据库把它们连在一起，然后把整套东西纳入版本控制，让它可以从 GitHub 部署。 แล็บนี้จะสร้างทั้งสองเครื่อง เชื่อมเข้าด้วยกันโดยใช้กูเกิลชีตเป็นฐานข้อมูล จากนั้นนำทั้งหมดเข้าสู่ระบบควบคุมเวอร์ชัน เพื่อให้ดีพลอยจากกิตฮับได้

The two machines. Whenever something does not work, ask first: which machine is this supposed to run on? Nearly every beginner problem with Google Sites is code written on the machine that cannot run it. 两台机器。每当有东西跑不起来时，先问一句：这段东西本来应该在哪台机器上运行？初学者在谷歌网站上遇到的问题，几乎都是把代码写在了跑不动它的那台机器上。 สองเครื่อง เวลามีอะไรไม่ทำงาน ให้ถามก่อนว่า สิ่งนี้ควรรันบนเครื่องไหน ปัญหาของมือใหม่บนกูเกิลไซต์เกือบทั้งหมด คือการเขียนโค้ดไว้บนเครื่องที่รันมันไม่ได้

🔤 The words you need

Twenty words. Learn these first and the rest of the lab reads like plain English. Tap a card to hear it, or open it for the longer story. 二十个词。先把这些学会，实验室后面的内容读起来就像大白话。点卡片可以听发音，展开可以看更详细的解释。 ยี่สิบคำ เรียนคำเหล่านี้ก่อน แล้วเนื้อหาที่เหลือจะอ่านง่ายขึ้นมาก แตะการ์ดเพื่อฟังเสียง หรือกดเปิดเพื่ออ่านคำอธิบายแบบยาว

Part 1 — Build a website with a real backend

1. The Words You Need (Glossary)

Learn the words first, or every later step will feel like guessing.

1. 你需要的词汇 — 先学会这些词，否则后面每一步都像在猜。

1. คำศัพท์ที่ต้องรู้ — เรียนคำศัพท์ก่อน ไม่อย่างนั้นทุกขั้นตอนต่อไปจะเหมือนการเดา

Term	Plain-English Definition
Google Site	A platform used to create and publish websites to share information with others for personal or business use.
Page	An individual document within a site structure that can be added, organized, or deleted via the Pages tab.
Section	A layout grouping on a page, often created using Content Blocks, that organizes text, images, and other elements.
Embed	A tool to integrate external content, like web addresses or Apps Script applications, directly into a site page.
Google Drive	The cloud-based storage service where files like Docs, Sheets, and Slides reside before being inserted into a site.
Apps Script	A JavaScript-based logic engine used to automate tasks, connect to Google APIs, and build custom web applications.
Web App	An Apps Script project deployed as a unique URL that serves a user interface through the HTML service.
doGet	A required script function that handles HTTP GET requests to serve the initial HTML content of a web app.
doPost	A script function used to handle HTTP POST requests, typically for sending data from a client to the server.
Deployment	The process of creating a functional, versioned instance of your script to be used as a web app.
Deployment ID	A unique string identifying a specific version of a script that has been published for use.
Execute as	A setting determining if a script runs using the developer’s permissions or the visitor’s permissions.
Who has access	A deployment permission defining whether the app is open to anyone, only those with a Google Account, or specific users.
Google Sheet as a Database	Using a spreadsheet to programmatically store, read, and manage data via the Apps Script Spreadsheet service.
iframe	The security-sandboxed window used by Google Sites to display embedded content and Apps Script web apps.
Authorization scope	A specific permission (like access to Drive or Sheets) that a script must request from a user to function.

2. The Two Machines: Core Architecture

The Site shows things. The Web App runs things. They are not the same machine.

2. 两台机器：核心架构 — 网站负责显示，网络应用负责运行。它们不是同一台机器。

2. สองเครื่อง: สถาปัตยกรรมหลัก — ไซต์ทำหน้าที่แสดงผล เว็บแอปทำหน้าที่รันโค้ด ทั้งสองไม่ใช่เครื่องเดียวกัน

Architecturally, a dynamic Google Site is composed of two distinct "machines" working in tandem. Google Sites serves as the content delivery platform—it is a secure, responsive container for text, images, and media. However, Sites cannot execute custom server-side code.

Apps Script serves as the backend logic engine. It performs the heavy lifting, such as querying a database (Google Sheets) or processing logic, and then serves the result into the Site. Because of the Iframe security boundary, the backend logic is sandboxed within the Site; it runs on Google's servers and is projected into the Site container.

Google Sites vs. Apps Script Web Apps

What each machine can do, and what it will never do.

谷歌网站与应用脚本网络应用的对比 — 每台机器能做什么，以及永远做不到什么。

เปรียบเทียบกูเกิลไซต์ กับ เว็บแอปแอปส์สคริปต์ — แต่ละเครื่องทำอะไรได้ และอะไรที่ทำไม่ได้เลย

Capability / Limitation	Google Sites (The Container)	Apps Script Web Apps (The Backend)
Capabilities	Add text, images, and content blocks; embed Drive files, YouTube videos, and maps; manage site-wide navigation.	Design custom HTML UIs; automate tasks (emails/invites); access Service APIs (Gmail, Sheets); process custom data.
Limitations	No custom server-side code on-page; restricted to predefined layouts and standard widgets.	Requires formal deployment/versioning; necessitates authorization for private data; subject to Google Service quotas.

The "Talk-To" Relationship: The Site acts as the host and visual frame. The Web App acts as a service provider. When the Site loads, it requests the Web App URL via an iframe, triggering the script to execute and serve the dynamic content.

3. Build the Front: Setting Up Your Site

Create the site, add pages, add text and pictures. No code yet.

3. 搭建前台：建立你的网站 — 创建网站、添加页面、放入文字和图片。这一步还不写代码。

3. สร้างส่วนหน้า: ตั้งค่าไซต์ของคุณ — สร้างไซต์ เพิ่มหน้า ใส่ข้อความและรูปภาพ ยังไม่ต้องเขียนโค้ด

To build your site container, follow these steps:

Navigate to sites.google.com/new.
Under "Start a new site," select a template or click "Blank (+)."
In the top left, click the Enter site name field and type your project name.
Press Enter.

Adding Layouts and Navigation:

Insert Tab: Use this sidebar to add Text boxes, Images, or Content Blocks (pre-set layout grids).
Pages Tab: Click this tab and hover over the Add (+) icon to create new pages or a "Full page embed" for your app.
Arrangement: Drag and drop elements to group text and images together; a blue line will appear when elements are ready to be grouped.

4. Google Drive Integration & Permissions

Drop live Drive files onto the page. Sharing settings decide who can see them.

4. 谷歌云端硬盘整合与权限 — 把云端硬盘里的文件直接放到页面上。共享设置决定谁能看到。

4. การเชื่อมกับกูเกิลไดรฟ์ และสิทธิ์การเข้าถึง — วางไฟล์จากไดรฟ์ลงบนหน้าเว็บได้เลย การตั้งค่าแชร์เป็นตัวกำหนดว่าใครเห็นได้

Google Sites integrates natively with Drive files, but visibility depends entirely on your sharing configuration.

Embedding Drive Content

Docs, Sheets, Slides, Forms, Calendar, Maps and YouTube all embed the same way.

嵌入云端硬盘内容 — 文档、表格、幻灯片、表单、日历、地图和 YouTube 的嵌入方式都一样。

การฝังเนื้อหาจากไดรฟ์ — เอกสาร ชีต สไลด์ ฟอร์ม ปฏิทิน แผนที่ และยูทูบ ฝังด้วยวิธีเดียวกันทั้งหมด

Open the Insert menu on the right.
For Docs, Sheets, or Slides: Scroll to the bottom of the menu, select the file type, choose your file, and click Insert.
For Media/Widgets: Use the specific menu items for YouTube, Calendar, or Map to insert interactive content.

Architect's Pro-Tip: Sharing Permissions Simply embedding a file does not grant access to your visitors. If a file is restricted, visitors will see a 404 or "Access Denied" error. To ensure visibility: 1. Set the Drive file sharing to "Anyone with the link" as a viewer. 2. For maximum compatibility, use the File > Share > Publish to the web option within the specific Doc or Sheet before embedding the provided link in your site.

5. Build the Back: Creating the Web App

Write doGet, then deploy. Saving alone changes nothing for visitors.

5. 搭建后台：创建网络应用 — 写好 doGet，然后部署。只是保存的话，访客那边不会有任何变化。

5. สร้างส่วนหลัง: สร้างเว็บแอป — เขียน doGet แล้วดีพลอย แค่กดบันทึกอย่างเดียวผู้เข้าชมจะไม่เห็นอะไรเปลี่ยน

The backend is a standalone Apps Script project that handles your logic and UI.

Go to script.google.com and create a New Project.
In the script editor, define your doGet(e) function.

Server-Side Logic (`Code.gs`)

The code that runs on Google's machines, not the visitor's.

服务器端逻辑 — 这段代码运行在谷歌的机器上，而不是访客的机器上。

ลอจิกฝั่งเซิร์ฟเวอร์ — โค้ดส่วนนี้รันบนเครื่องของกูเกิล ไม่ใช่บนเครื่องของผู้เข้าชม

Critical: You must use createTemplateFromFile().evaluate() to process any dynamic scriptlets (<?= ?>) in your HTML.

function doGet(e) { // Generate a template and evaluate it to run server-side scriptlets return HtmlService.createTemplateFromFile('Index').evaluate(); } // Function to be called by the HTML template to retrieve data function getSheetData() { const sheetId = 'YOUR_SHEET_ID_HERE'; return SpreadsheetApp.openById(sheetId).getActiveSheet().getDataRange().getValues(); }

New Deployment Settings

Execute as and Who has access. Get these two wrong and nothing works.

新建部署的设置 — 执行身份和访问权限。这两项设错，什么都跑不起来。

การตั้งค่าเมื่อสร้างดีพลอยใหม่ — รันในนามของ และ ใครเข้าถึงได้ ถ้าตั้งสองอย่างนี้ผิด ทุกอย่างจะไม่ทำงาน

Click Deploy > New deployment.
Select Type: Web app.
Execute as: Select Me. This is vital for "Database" access; it allows the app to read your private Google Sheet even if the site visitor does not have access to that Sheet.
Who has access: Select Anyone to allow the Site iframe to load the content for all visitors.

6. The Database: Google Sheets Integration

A spreadsheet is a perfectly good database for a small site.

6. 数据库：整合谷歌表格 — 对小网站来说，一个电子表格就是很好的数据库。

6. ฐานข้อมูล: การเชื่อมกับกูเกิลชีต — สำหรับเว็บเล็ก ๆ สเปรดชีตก็เป็นฐานข้อมูลที่ดีพอแล้ว

Apps Script interacts with Sheets as a grid of two-dimensional arrays, where each inner array represents a row of data.

Create a Google Sheet and copy its ID from the URL (the string between /d/ and /edit).
Use these logic patterns for data operations:

Read and Write Patterns

Read rows out, append rows in. Two directions, a few lines each.

读取与写入的写法 — 把行读出来，把行追加进去。两个方向，各只要几行代码。

รูปแบบการอ่านและเขียนข้อมูล — อ่านแถวออกมา และเพิ่มแถวเข้าไป สองทิศทาง ใช้โค้ดไม่กี่บรรทัด

// Read Logic: Retrieves the entire sheet as a 2D array function readData(sheetId) { const data = SpreadsheetApp.openById(sheetId).getActiveSheet().getDataRange().getValues(); return data; // Result: [[Row1Col1, Row1Col2], [Row2Col1, Row2Col2]] } // Write Logic: Appends a new data row to the bottom function appendData(sheetId, newRowArray) { const sheet = SpreadsheetApp.openById(sheetId).getActiveSheet(); sheet.appendRow(newRowArray); // e.g., ['2023-10-27', 'User Submission'] }

7. Wire Them Together: The Embed

Paste the Web App URL into the Site. This is the moment it becomes one website.

7. 把两者接起来：嵌入 — 把网络应用的网址粘贴到网站里。到这一刻，它才真正变成一个网站。

7. เชื่อมทั้งสองเข้าด้วยกัน: การฝัง — วาง URL ของเว็บแอปลงในไซต์ ตรงนี้แหละที่มันกลายเป็นเว็บไซต์เดียวกัน

To connect your backend logic to the front end, you must embed the Web App's "Exec" URL.

Copy the Web App URL from your Apps Script deployment.
In Google Sites, go to Insert > Embed.
Paste the URL under the By URL tab.

HTML Template with Data Wiring (`Index.html`)

The page the backend hands back, with real data already inside it.

带数据绑定的 HTML 模板 — 后端交回来的页面，里面已经装好了真实数据。

เทมเพลต HTML ที่ต่อกับข้อมูล — หน้าเว็บที่แบ็กเอนด์ส่งกลับมา โดยมีข้อมูลจริงอยู่ข้างในแล้ว

This template uses server-side scriptlets to loop through the 2D array provided by the getSheetData() function in Code.gs.

<!DOCTYPE html> <html> <head><base target="_top"></head> <body> <h1>Sheet Data Records</h1> <table border="1"> <? var data = getSheetData(); // Server-side function call ?> <? for (var i = 0; i < data.length; i++) { ?> <tr> <? for (var j = 0; j < data[i].length; j++) { ?> <td><?= data[i][j] ?></td> <? } ?> </tr> <? } ?> </table> <p>Last Updated: <?= new Date() ?></p> </body> </html>

8. Permissions and Authorization

The most common failure of all. Learn to read the warning screen.

8. 权限与授权 — 最常见的失败就在这里。要学会读懂那个警告页面。

8. สิทธิ์และการอนุญาต — จุดที่พังบ่อยที่สุด ต้องอ่านหน้าจอคำเตือนให้เป็น

The Authorization Lifecycle

Why it asks, when it asks again, and what the scary screen means.

授权的完整流程 — 它为什么要问、什么时候会再问一次，以及那个吓人的页面是什么意思。

วงจรการขออนุญาต — ทำไมมันถึงถาม เมื่อไรจะถามอีก และหน้าจอที่ดูน่ากลัวนั้นหมายถึงอะไร

Apps Script identifies needed permissions by scanning your code for service calls (e.g., SpreadsheetApp).

User Prompt: When you first run or deploy the script, an "Authorization required" dialog appears.
Granular Consent: You must grant access to the specific scopes the script detected.
Unverified App Warning: If you see this screen, click Advanced and then Go to [Project Name] (unsafe) to proceed. This is standard for private scripts that haven't undergone Google's public verification process.

9. Publish: Going Live

Choose who can view it, then connect your own domain name.

9. 发布：正式上线 — 选择谁可以浏览，然后接上你自己的域名。

9. เผยแพร่: ออนไลน์จริง — เลือกว่าใครดูได้ แล้วเชื่อมกับชื่อโดเมนของคุณเอง

Changes in the editor are not visible until you publish them.

Click the Publish button in the top right.
Web address: Enter a unique URL slug (e.g., my-project-dashboard).
Custom Domains: To use a domain you own, navigate to Settings (gear icon) > Custom domains and follow the setup wizard to connect your URL.

10. Put Everything Away: Clean Up

Unpublish, undeploy, delete. Leave nothing running that you forgot about.

10. 收拾干净：清理 — 取消发布、取消部署、删除。不要留下你已经忘记的东西还在跑。

10. เก็บกวาดให้เรียบร้อย — ยกเลิกเผยแพร่ ยกเลิกดีพลอย และลบทิ้ง อย่าปล่อยให้มีอะไรทำงานค้างไว้

To fully decommission your project, follow these specific steps:

Unpublish the Site: Click the drop-down next to "Publish" and select Unpublish.
Undeploy the Web App: In the Apps Script editor, go to Deploy > Manage deployments. Select the active deployment and click Archive or Remove to stop the URL from resolving.
Delete Files: Use the "More" (three dots) menu on the Google Sites home screen to Remove the site. In the Apps Script dashboard, move the project to the trash.

11. Ten Things That Will Go Wrong (Troubleshooting)

Symptom, cause, fix. Read this before you ask anyone for help.

11. 十个一定会出错的地方 — 症状、原因、解决办法。在向别人求助之前先看这一段。

11. สิบเรื่องที่จะต้องพังแน่ ๆ — อาการ สาเหตุ วิธีแก้ อ่านตรงนี้ก่อนจะไปถามใคร

Symptom	Probable Cause	Fix
"Authorization required" error	Code changes added new services that weren't authorized.	Manually run any function in the editor to trigger the dialog.
"This app is blocked"	Script is using sensitive scopes without verification.	Click "Advanced" and proceed to the script (unsafe).
"File indexing issue" error	The embedded file reached its share limit.	Create a copy of the file and embed the new copy.
"Embedded files" tab doesn't display	Site is not indexed or has no embedded Drive files.	Republish the site to trigger the indexing process.
"Website won't let you add content"	The target website owner has blocked embedding.	Contact the source website owner for permission.
"File reached share limit"	Too much traffic to a single embedded Drive file.	Distribute the load by using copies of the file.
Scriptlets show as plain text	Used `createHtmlOutputFromFile` instead of template.	Change code to `createTemplateFromFile('Index').evaluate()`.
Access Denied for visitors	Drive file sharing is too restrictive.	Set Drive file to "Anyone with link" or "Publish to web."
Data not updating in Site	Web app was not updated to a new version.	Create a "New deployment" to push changes to the Site.
Site changes not appearing	The site editor was not published.	Click the "Publish" button to push the latest draft live.

12. Points to Remember

If you remember nothing else, remember these.

12. 要记住的要点 — 如果别的都忘了，至少记住这些。

12. ข้อที่ต้องจำ — ถ้าจำอย่างอื่นไม่ได้ ขอให้จำข้อเหล่านี้ไว้

Google Sites is a content delivery platform; it cannot execute custom server-side logic.
Apps Script Web Apps must use a doGet() function to serve HTML content.
Client-side JavaScript in Google Sites must be wrapped inside <script> tags.
Apps Script treats Google Sheets as a data grid of two-dimensional arrays.
Authorization scopes are automatically determined by scanning for service calls like GmailApp.
Drive sharing permissions are independent of Site publishing settings and must be set manually.
"Execute as: Me" allows visitors to interact with data they don't personally have access to.
Scriptlet code (<? ... ?>) executes *once* on the server before the page is served to the user.
Sites must be published/indexed for "Embedded files" to appear in internal search results.
Access to scripts can be revoked at any time via the Security section of your Google Account.

Part 2 — Deploying to Google Sites from GitHub

1. The Hard Truth: Limitations of the Google Sites Platform

There is no git push to a Google Site. None. The shell is always built by hand.

1. 残酷的事实：谷歌网站平台的限制 — 没有办法用 git push 把内容推到谷歌网站。完全没有。外壳永远得手工搭建。

1. ความจริงที่ต้องยอมรับ: ข้อจำกัดของกูเกิลไซต์ — ไม่มีวิธี git push เข้ากูเกิลไซต์ ไม่มีเลย โครงของไซต์ต้องสร้างด้วยมือเสมอ

the sources confirm that no public API, CLI, or Git-based method currently exists for programmatically writing content directly into native Google Sites elements.

The Core Constraint

Google Sites is strictly a manual, browser-based builder. The consequence of this architecture is that the "shell" of your site—its navigation, page hierarchy, and native text/image blocks—cannot be deployed or modified via a repository.

Warning: The Site itself must be constructed and structured by hand in the browser at sites.google.com/new. Automation is reserved for the components you embed within this manual shell.

2. The Hybrid Architecture: What IS Deployable

You cannot deploy the Site, but you can deploy both things it displays.

2. 混合架构：哪些部分可以自动部署 — 网站本身不能自动部署，但它显示的那两样东西都可以。

2. สถาปัตยกรรมผสม: ส่วนไหนที่ดีพลอยได้ — ตัวไซต์ดีพลอยไม่ได้ แต่สองสิ่งที่ไซต์แสดงอยู่นั้นดีพลอยได้ทั้งคู่

While the shell is manual, we can automate the two primary "Tracks" that provide functionality: an embedded web frontend and an Apps Script backend.

Source	Automation	Deploy Targets	Final Presentation
GitHub Repository	GitHub Actions	GitHub Pages (Frontend)	Google Site (Embed via URL)
GitHub Repository	GitHub Actions	Google Apps Script (Backend)	Google Site (Apps Script Gadget)

3. Track A: Deploying the Frontend to GitHub Pages

Push HTML to a repo, GitHub publishes it, the Site embeds that address.

3. 路线 A：把前端部署到 GitHub Pages — 把 HTML 推到仓库，GitHub 负责发布，网站再嵌入那个地址。

3. เส้นทาง A: ดีพลอยฟรอนต์เอนด์ไปที่กิตฮับเพจเจส — พุช HTML ขึ้น repo กิตฮับเผยแพร่ให้ แล้วไซต์ก็ฝัง URL นั้นเข้าไป

GitHub Pages serves as our automated hosting layer. A significant advantage here is that GitHub Pages supports over 750 MIME types, allowing you to serve specialized file extensions that the native Google Sites platform might otherwise block or misinterpret.

Step-by-Step Instructions

Create a Repository: Initialize a repository on GitHub.
Add Entry Point: Create an index.html file in the root directory.
Configure Settings: Navigate to Settings > Pages.
Select Source: Under "Build and deployment," click the "Source" dropdown. Explicitly select "GitHub Actions" (do not use the default "Deploy from a branch" if you intend to use the workflow below).

Workflow Configuration

Create .github/workflows/deploy.yml to publish on every push to main:

name: Deploy to GitHub Pages on: push: branches: ["main"] permissions: contents: read pages: write id-token: write jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: '.' - name: Deploy to GitHub Pages uses: actions/deploy-pages@v4

URL Retrieval

Find your live URL under Settings > Pages once the Action completes.

4. Embedding the Pages Site into Google Sites

Once embedded, a git push updates the page. You never republish the Site.

4. 把 Pages 页面嵌入谷歌网站 — 嵌入之后，一次 git push 就能更新页面。网站本身不需要重新发布。

4. ฝังหน้าจากเพจเจสลงในกูเกิลไซต์ — เมื่อฝังแล้ว แค่ git push หน้าก็อัปเดต ไม่ต้องกดเผยแพร่ไซต์ใหม่

Once the frontend is live, integrate it into your manual shell.

Integration Steps

Open your site in the Google Sites editor.
Click Insert > Embed.
Select By URL and paste your GitHub Pages URL.

Full Page Embed

For a seamless, "native" application feel, use a Full Page Embed:

Click the Pages tab.
Hover over Add (+) and select Full page embed.
Paste the URL and click Insert.

Synchronization Clarity

While the embedded content updates automatically when the GitHub Pages site changes, Google documentation for "Add a page or section of content from another website" requires a final manual step for the public to see changes to the Site shell: At the top right, click Publish. If changes do not appear, you must republish or refresh the Site to ensure the shell is indexed correctly.

5. Track B: Deploying the Backend with clasp

clasp turns the browser-only script editor into ordinary files in a repo.

5. 路线 B：用 clasp 部署后端 — clasp 把只能在浏览器里编辑的脚本，变成仓库里普通的文件。

5. เส้นทาง B: ดีพลอยแบ็กเอนด์ด้วย clasp — clasp เปลี่ยนสคริปต์ที่แก้ได้แต่ในเบราว์เซอร์ ให้เป็นไฟล์ธรรมดาใน repo

To manage logic (emails, database triggers, or Workspace automation) via GitHub, use the Command Line Apps Script Projects (clasp) tool.

Hard Truth: Clasp 3.x TypeScript Limitation

Note that Clasp 3.x no longer transpiles TypeScript code. If your project uses TypeScript, you must use a bundler like Rollup or a template like wildh0g/apps-script-engine-template to transform code before pushing.

Local Setup

Install: npm install -g @google/clasp.
Enable API: You must enable the Apps Script API at script.google.com/home/usersettings.
Login: Run clasp login.
Initialize: Run clasp create or clasp clone <Script ID>.

Required Files: Ensure .clasp.json (config) and appsscript.json (manifest) are in your repository. Use clasp push to upload and clasp deploy to version your code.

6. Automating Track B in GitHub Actions

Store the credential as a secret so the robot can log in without you.

6. 用 GitHub Actions 自动化路线 B — 把凭证存成 secret，机器人就能自己登录，不用你动手。

6. ทำเส้นทาง B ให้อัตโนมัติด้วยกิตฮับแอคชันส์ — เก็บข้อมูลรับรองไว้เป็น secret เพื่อให้ระบบล็อกอินเองได้โดยไม่ต้องรอคุณ

Headless CI requires secure credential management.

Headless CI Instructions

Secret Extraction: Your local clasp login creates a .clasprc.json file. This is the "Master Key" to your Google Script environment; handle it with extreme care.
GitHub Secret: Copy the contents of .clasprc.json and store it in GitHub Secrets as CLASPRC_JSON.

Workflow Configuration

name: Deploy Apps Script on: [push] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: {node-version: '20'} - run: npm install -g @google/clasp - name: Auth Clasp run: echo '${{ secrets.CLASPRC_JSON }}' > ~/.clasprc.json - run: clasp push --force

Warning: While ~/.clasprc.json is the standard convention for Linux runners, the provided Google/Clasp documentation does not explicitly confirm this path.

7. Keeping the Deployment URL Stable

Update the existing deployment. A new one gets a new URL and breaks your embed.

7. 让部署网址保持不变 — 更新现有的部署。新建部署会得到新网址，把你的嵌入弄坏。

7. รักษา URL ของดีพลอยให้คงเดิม — ให้อัปเดตดีพลอยเดิม ถ้าสร้างใหม่จะได้ URL ใหม่ และทำให้ที่ฝังไว้พัง

In Google Apps Script, creating a "new deployment" generates a new unique ID, which breaks existing embeds in Google Sites.

Actionable Step: To ensure the Site embed remains stable, do not create a new ID. Instead, update the existing deployment ID with your new code version using:

clasp update-deployment <deploymentId>

8. Git Governance: What to Commit and What to Ignore

Credentials never go in git. Not once, not privately, not for a minute.

8. 仓库管理：什么该提交，什么该忽略 — 凭证绝对不能进 git。一次都不行，私有仓库也不行，一分钟也不行。

8. การจัดการ git: อะไรควรคอมมิต อะไรควรละเว้น — ข้อมูลรับรองห้ามเข้า git เด็ดขาด ไม่ว่าครั้งเดียว ไม่ว่า repo ส่วนตัว ไม่ว่านาทีเดียว

Security is paramount when integrating cloud environments.

File Name	Git Status	Reason
`index.html`	Commit	Frontend Source.
`.clasp.json`	Commit	Project Linking Config.
`appsscript.json`	Commit	Script Manifest/Permissions.
`.clasprc.json`	IGNORE	Sensitive Credentials (Master Key).
`node_modules/`	IGNORE	Managed Dependencies.

9. Choosing a Track: Decision Matrix

Most pages need no backend at all. Be honest about which one you are building.

9. 如何选择路线：决策表 — 大多数页面根本不需要后端。要老实判断你在做的是哪一种。

9. เลือกเส้นทางไหนดี: ตารางตัดสินใจ — หน้าเว็บส่วนใหญ่ไม่ต้องมีแบ็กเอนด์เลย ให้ซื่อสัตย์ว่าคุณกำลังสร้างแบบไหน

Method	Best For...	Architectural Trade-off
Direct Build	Static text and images.	Manual only; no automation.
GitHub Pages Embed	Custom UI/UX, JS libraries.	Browser-side execution.
Apps Script Backend	Automation, Workspace hooks.	Server-side execution.

10. Failure Modes: Symptom, Cause, and Fix

Blank frames, refused connections, stale content. All of them have a known cause.

10. 常见故障：症状、原因、解法 — 空白框、拒绝连接、内容不更新。这些都有已知的原因。

10. อาการพัง: อาการ สาเหตุ วิธีแก้ — กรอบว่างเปล่า เชื่อมต่อไม่ได้ เนื้อหาไม่อัปเดต ทั้งหมดนี้มีสาเหตุที่รู้อยู่แล้ว

Symptom	Cause	Fix
Blank frame or "Refused to connect."	Permissions/X-Frame-Options.	Check sharing settings or contact site owner.
`clasp push` fails.	Apps Script API disabled.	Enable at `script.google.com/home/usersettings`.
CI clasp auth fails.	Secret is stale or missing.	Run `clasp login` locally and update `CLASPRC_JSON`.
Stale content after push.	Caching or Site not republished.	Refresh browser or click Publish in Google Sites.

11. Points to Remember

The short version of everything above.

11. 要记住的要点 — 以上所有内容的精简版。

11. ข้อที่ต้องจำ — สรุปสั้น ๆ ของทุกอย่างข้างบน

Google Sites cannot be fully deployed via Git; the site shell is a manual, browser-based construct.
Use GitHub Pages to bypass Google Sites' native file restrictions and serve custom code.
The Apps Script API must be toggled "On" in your Google user settings for clasp to function.
Never commit .clasprc.json; it grants full access to your Google Script environment.
Google Sites requires you to click "Publish" to reflect structural or indexing changes.
Use clasp update-deployment to maintain stable URLs and avoid breaking Site embeds.
GitHub Pages allows you to serve 750+ MIME types, bypassing native Google Sites file restrictions.
Clasp 3.x does not transpile TypeScript; use a separate bundler like Rollup for TS projects.

Addendum — clasp 2.x vs 3.x command names

Verified directly against the google/clasp README, because the generated tutorials above mix the two generations. If a command “does not exist”, you are almost certainly reading a 2.x tutorial while running a 3.x binary.

clasp 2.x	clasp 3.x	What it does
`clasp deploy`	`clasp create-deployment`	Create a NEW deployment (new ID — breaks your embed)
`clasp deploy -i <id>`	`clasp update-deployment <id>`	Update an EXISTING deployment (ID stays — embed keeps working)
`clasp undeploy <id>`	`clasp delete-deployment <id>`	Remove a deployment
`clasp open`	`clasp open-script`	Open the script in the browser editor
`clasp open --web`	`clasp open-web-app`	Open the deployed web app
`clasp apis enable <api>`	`clasp enable-api <api>`	Enable an advanced service
`clasp logs --open`	`clasp open-logs`	Open Cloud logs

Verified. The README states that other commands were also renamed but retain aliases for compatibility — which is why clasp deploy often still appears to work on 3.x, and why mixed tutorials survive in the wild.

The one that actually bites. create-deployment mints a new deployment ID, and your Google Site embed still points at the old URL. The page keeps serving stale code and nothing errors. To ship a change to a live embed you want update-deployment <id>, every time.

clasp 3.x dropped TypeScript transpiling. If your repo is TypeScript you must bundle first (Rollup, or a template such as WildH0g/apps-script-engine-template) and push the compiled output.

Where this came from

Both tutorials above were generated by NotebookLM from 22 primary sources — Google’s own Apps Script guides, the Google Sites Help Center, GitHub’s Pages and Actions docs, and the google/clasp README. Nothing was written from memory.

Honesty notes carried through from the sources. Where the sources did not confirm something, the tutorials say so instead of guessing — specifically the “Who has access” option names, and the exact ~/.clasprc.json path on a CI runner.

There is no git push to a Google Site. New Google Sites exposes no public write API; the old Sites API covered Classic Sites only. The Site shell is always built by hand. What you deploy from GitHub are the two things the Site displays.