building-webflow-pages

Webflow 페이지 구축하기

개요

Webflow MCP 쓰기 도구는 종종 요청과 다른 작업을 수행했음에도 성공을 반환합니다. 클래스 이름이 변경되고, 이미지가 아무것도 바인딩되지 않으며, 스타일이 잘못된 중단점에 적용됩니다. 모든 쓰기 작업은 다시 읽어야 합니다.

핵심 원칙: 성공 응답은 증거가 아닙니다. 요소 트리가 증거입니다.

CMS 항목, 블로그 게시물, 페이지 SEO의 경우 CMS 중심의 퍼블리싱 스킬을 대신 사용하세요. 이 스킬은 디자이너 표면(요소, 스타일, 에셋, 사용자 정의 코드)을 다룹니다.

무쇠 법칙

현재 대화에서 명시적 승인 없이 프로덕션에 퍼블리싱하지 마십시오.

사이트 퍼블리시는 모든 페이지의 모든 스테이징된 디자이너 변경 사항을 한 번에 배포하며, 사용자가 만들지 않은 작업과 프로덕션에서 여전히 접근 가능한 미등록 페이지도 포함됩니다. "이전에 퍼블리시하라고 이미 말했어"라는 말은 작업 간에 이어지지 않습니다. 다시 물어보세요.

스테이징은 다릅니다. 이것이 작업이 검토되는 방식입니다. 스테이징 서브도메인(빈 사용자 정의 도메인 목록)에만 퍼블리싱하는 것은 수정 후 정상적인 단계이며, 그다음 스테이징에서 QA를 진행합니다. 기본 프로덕션 도메인에만 퍼블리싱하고, 사이트의 모든 도메인에는 절대 하지 마세요. 승인 후에만 가능합니다.

아홉 가지 함정

1. whtml_builder가 충돌하는 클래스의 이름을 변경합니다

해당 이름의 스타일이 존재하는 상태에서 hp2-proof를 요청하면 hp2-proof-1을 받습니다. hp2-proof-n을 요청하면 hp2-proof-n-1을 받습니다. 연쇄 충돌은 hp2-proof-link-1-2를 생성합니다. 래퍼 div는 종종 클래스를 전혀 얻지 못합니다.

오류는 없습니다. 그러면 헤드 CSS는 존재하지 않는 클래스를 대상으로 하고, 등록된 스크립트의 querySelectorAll('.hp2-proof')는 0개의 요소와 일치하므로 스크롤 애니메이션이 실행되지 않습니다.

삽입 후에는 항상 query_elements로 스타일을 확인하고, 실제 styleNames를 읽은 후, 그에 맞게 CSS와 스크립트 선택기를 작성하세요. 클래스가 없는 래퍼는 .parent-class > div로 접근할 수 있습니다.

2. html의 클래스는 이미 존재하는 경우에만 적용됩니다

html 매개변수에서 참조된 클래스는 해당 스타일이 사이트에 이미 존재하거나 동일한 호출의 css 매개변수에 정의된 경우에만 바인딩됩니다. 그렇지 않으면 요소가 클래스 없이 삽입되고 여전히 성공을 보고합니다. 사용하는 모든 클래스를 css에 정의하세요.

빌더는 하위 선택기도 지원하지 않습니다. 단일 클래스와 콤보 클래스(.a.b)를 사용하세요. @media와 clamp()는 괜찮습니다.

3. whtml_builder는 단일 루트 요소가 필요합니다

최상위 수준의 여러 형제 요소는 실패하거나 부분적으로만 삽입됩니다. 하나의 컨테이너로 감싸세요.

4. 마크업으로 삽입된 이미지는 바인딩되지 않습니다

html의 <img>는 "자산 라이브러리에 존재하지 않음"과 함께 partial_success를 반환합니다. 요소를 삽입한 다음 set_image_asset과 자산 ID로 바인딩하세요.

5. update_style은 breakpoint가 아닌 breakpoint_id로 범위를 지정합니다

breakpoint 키는 자동으로 무시되고 쓰기는 기본 중단점에 적용되어 데스크탑을 덮어씁니다. 응답은 범위가 지정된 쓰기가 작동한 경우에만 breakpoints 키를 표시합니다. breakpoint_id를 명시적으로 전달하고 다시 읽어 확인하세요.

6. set_style은 추가하지 않고 대체합니다

set_style은 기존의 모든 스타일을 제거하고 전달한 것만 적용합니다. 클래스를 추가하려면 먼저 현재 styleNames를 읽고 전체 목록을 전달하세요.

7. set_page_freeform_code는 전체 블록을 대체합니다

페이지 헤드 및 푸터 사용자 정의 코드는 페이지나 스타일 도구가 아닌 data_scripts_tool에 있습니다: get_page_freeform_code와 set_page_freeform_code, location: "head"와 함께 사용하세요.

쓰기는 전부 아니면 전무(all-or-nothing)입니다. 추가 기능은 없습니다. 항상 현재 블록을 get하고, 문자열을 수정한 후, set으로 전체를 다시 설정하세요. 조각을 쓰면 헤드에 있던 다른 모든 것이 자동으로 삭제됩니다. 또한 일부 요금제에서는 <script> 태그를 거부하므로, 스크립트는 임베드(아래 참조)에 넣어야 합니다.

8. API를 통해 만든 페이지는 기본 CSS를 상속받지 않습니다

사이트가 기본 CSS 구성 요소에서 루트 글꼴 크기를 설정하는 경우(예: 1rem이 10px이 되도록 html{font-size:.625rem}), API를 통해 생성된 페이지는 해당 구성 요소를 받지 못합니다. 모든 것이 디자이너와 퍼블리시 시 1.6배 너무 크게 렌더링됩니다. 모든 새 페이지의 첫 번째 요소는 기본 CSS 구성 요소여야 합니다. 스타일을 지정하기 전에 확인하세요.

9. 자산 생성 출력이 사라지고 바인딩 속도가 제한됩니다

특정 크기 미만의 create_asset 출력은 유지되지 않으므로, 22개 자산 배치는 인라인으로 출력되며 즉시 기록해야 합니다. set_image_asset은 읽기와 쓰기를 각각 수행합니다: 분당 약 10번의 바인딩 후 429 오류가 발생합니다. 10개씩 배치로 바인딩하고 1분 간격을 두고, 이름, 자산 ID, 날짜, 서명 행의 테이블을 유지하세요.

사용자 정의 코드 및 스크립트

일부 계정에서는 페이지 스크립트 API가 차단됩니다. 페이지에서 JavaScript를 실행하려면:

1. register_inline_script (최대 2000자) 또는 register_hosted_script를 사용하세요.
2. data_element_settings_tool을 통해 code 키로 편집된 페이지의 HtmlEmbed 요소 안에 있는 <script src>에서 반환된 호스팅 URL을 참조하세요.

페이지를 섹션당 하나의 임베드와 애니메이션 라이브러리와 스크립트를 가져오는 로더 임베드로 구성하세요. 등록된 스크립트를 변경하는 대신 표시 이름을 버전 관리하세요(sections.v17). update_registered_script는 인라인 스크립트에서 실패하고, 버전 관리된 이름은 임베드의 URL 하나를 편집하여 롤백할 수 있습니다. 페이지 CSS도 같은 방식으로 버전 관리하여 호스팅하세요.

초안 미리보기

초안 페이지는 API를 통해 게시된 상태로 전환할 수 없으며, 페이지 분기는 엔터프라이즈 기능입니다. 따라서 로컬 복제본에 대해 초안 QA를 수행하세요: 라이브 내비게이션 및 푸터 마크업, 사이트 CSS, 기본 CSS 규칙, CDN의 애니메이션 라이브러리.

숨겨진 탭이나 헤드리스 창에서는 애니메이션 티커가 일시 중지됩니다. 강제로 실행하려면:

gsap.ticker.lagSmoothing(0); gsap.ticker.tick();

숨겨진 창의 스크린샷은 접힌 부분 아래를 빈 칸으로 그립니다. 스크린샷을 위해 섹션을 보기로 가져오려면 body를 변환하고, 실제 scrollTo 후에 ScrollTrigger.update()를 호출하세요.

자산

세 단계가 있으며, 세 번째 단계를 놓치는 경우가 많습니다:

1. create_asset에 파일 이름과 원시 바이트의 MD5(32자리 소문자 16진수)를 전달합니다.
2. 반환된 uploadUrl에 바이트를 multipart/form-data로 POST하고, 모든 uploadDetails 필드와 함께 file 아래에 파일을 추가합니다. 201을 기대하세요.
3. 동일한 이름과 해시로 create_asset을 다시 호출하여 마무리합니다.

CDN URL은 https://cdn.prod.website-files.com/<siteId>/<assetId>_<filename>입니다. 작동하는 curl 레시피는 asset-upload.md를 참조하세요.

비디오는 동일한 형식(video/mp4, video/webm)으로 업로드되며, 임베드에서 autoplay muted loop playsinline 및 포스터와 함께 참조됩니다. 홈페이지 비디오는 대역폭을 많이 소모하므로, 작은 루프와 라이트 파일을 휴대폰에 제공하세요.

속도 제한

읽기 작업(query_elements, get_all_elements, get_settings)은 에셋 및 컬렉션 엔드포인트를 사용하며, 많은 에셋 작업 후 429를 반환하기 시작합니다. 쓰기 작업은 계속 작동합니다. query_elements가 429를 반환하면, get_all_elements를 깊이 2로 호출하면 일반적으로 성공합니다.

배치 읽기: 한 번의 query_elements 호출로 여러 쿼리를 수행할 수 있습니다.

검증 체크리스트

모든 빌드 세션 후에 이것을 실행하고 결과를 보고하세요. 의도는 보고하지 마세요.

• query_elements로 도입한 모든 클래스의 스타일 이름을 확인하세요. 실제 이름이 CSS와 스크립트가 대상으로 하는 것과 일치해야 합니다.
• 삽입된 모든 이미지의 설정에 assetId가 있습니다.
• 중단점 스타일이 의도한 중단점에서 다시 읽힙니다.
• 헤드/푸터 블록에 편집 전에 있던 모든 것이 여전히 포함되어 있습니다.
• 임베드의 등록된 스크립트 URL이 방금 등록한 버전과 일치합니다.
• 자산 CDN URL이 예상된 콘텐츠 유형과 크기로 200을 반환합니다.
• 기본 CSS 구성 요소가 페이지의 첫 번째 요소입니다.
• 스테이징된 페이지가 구축한 것과 일치합니다. 스테이징 HTML을 가져와 확인하고, 추측하지 마세요.

경고 신호

• "도구가 성공을 반환했으므로 클래스가 적용되었습니다."
• "지금 CSS를 작성하고 나중에 클래스 이름을 확인하겠습니다."
• "작은 변경이므로 헤드 블록을 직접 작성하겠습니다."
• "사용자가 이 프로젝트 초반에 퍼블리싱을 승인했습니다."
• "일관성을 유지하기 위해 모든 도메인에 퍼블리싱하겠습니다."

이 모든 것은 계속하기 전에 트리를 다시 읽으라는 의미입니다.